# Submetry MCP — read-only analytics

Submetry exposes a stateless Streamable HTTP endpoint at:

https://api.submetry.com/v1/mcp

The web proxy at https://submetry.com/api/v1/mcp reaches the same backend. In local development, use http://localhost:3000/api/v1/mcp (or your actual development port).

## ChatGPT / Codex plugin with OAuth

The plugin sources in `plugins/submetry/` package three guided analyses: weekly review, onboarding diagnosis and version comparison. OAuth connections expose exactly four aggregate tools: `list_apps`, `get_stats`, `get_cohorts`, and `get_events`. Individual-user access is unavailable through OAuth. The plugin requires a Submetry owner account and explicit selection of existing apps on `/app/connect`. New apps are not included automatically. Manage and revoke connections on `/app/connections`.

The authorization server uses `https://api.submetry.com` as its issuer and `https://api.submetry.com/v1/mcp` as its resource. Discovery is at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource/v1/mcp`. Public Dynamic Client Registration, authorization-code flow, mandatory S256 PKCE and `analytics:read` are supported. OAuth tokens do not grant REST API, management, ingestion or individual-user access. Access tokens expire after one hour; refresh tokens rotate and expire after 30 days of inactivity. Reusing an old refresh token revokes the whole connection.

OAuth tool results have `{data, meta}` structured output. Aggregates include effective dates, timezone, environment, USD currency, available freshness/generation timestamps and limitations. Null or unavailable data must not be treated as zero. Personal identity fields, raw properties, onboarding answers and keys are excluded. Property-derived onboarding/paywall/product labels are replaced with response-local group names; these do not identify progression order and cannot be matched across queries. Use the explicit funnel definitions for ordered conversion analysis.

Build and validate the submission draft with `npm run plugin:build` and `npm run plugin:check`. Package creation does not deploy OAuth or publish a listing. See `docs/openai-plugin-submission.md` for deployment, review-account, legal/publisher metadata, domain-verification and OpenAI connection prerequisites.

## Create an analytics key

Open **API & MCP** in your workspace. Give the key a name and choose all apps or a specific selection. Copy the `sub_ro_…` secret immediately: it is shown only once. Keep it in your assistant's secret store. Submetry stores its SHA-256 hash, owner, and scope; it never returns the secret from the key list.

“All apps” includes future apps created in your workspace. A selection includes only the selected active apps. Archived or deleted apps are inaccessible. Revoking a key takes effect on its next request.

Public ingestion keys (`sub_pk_…`), private server keys (`sub_sk_…`), session cookies, and team invitation tokens do not authenticate MCP requests.

## Connect Codex

Set the `SUBMETRY_READ_ONLY_KEY` environment variable securely, then add this entry to your Codex configuration:

```toml
[mcp_servers.submetry]
url = "https://api.submetry.com/v1/mcp"
bearer_token_env_var = "SUBMETRY_READ_ONLY_KEY"
```

Restart Codex with that environment variable available. Never commit the key to your repository.

For another assistant supporting remote HTTP MCP servers, add the endpoint and configure the `Authorization: Bearer sub_ro_…` header using its secret field. Exact setup controls depend on the client.

## Available tools

The following five-tool list applies to the existing key-based connection, not to OAuth:

- `list_apps`: list the apps accessible with the key.
- `get_stats`: activation, funnels, conversion, and revenue dashboard for `app_id`.
- `get_cohorts`: retention cohorts for `app_id`.
- `get_events`: aggregate event counts for `app_id`.
- `get_user`: a single identity journey for `app_id` and `user_id`.

App tools accept optional `days` (1–366), `from`, `to`, `timezone`, `environment`, `country`, `app_version`, `source`, `paywall`, `product`, and `platform`. Environment defaults to `production` and also accepts `debug`, `sandbox`, `testflight`, or `all`. Defaults, freshness, privacy-deletion pauses, and query availability match the dashboard REST endpoints. No tool writes settings, grants access, ingests events, or deletes data.

Example request to your assistant:

> List my apps, then compare onboarding and trial conversion over the last 30 days. Explain the largest drop-off and cite the reported counts and freshness.

## HTTP protocol

This endpoint supports MCP versions `2025-11-25`, `2025-06-18`, and `2025-03-26` using the initialization handshake. It intentionally does not advertise the newer `2026-07-28` wire protocol. It follows the [2025-11-25 Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).

Send each JSON-RPC request via POST with `Content-Type: application/json`, `Accept: application/json, text/event-stream`, and your Bearer key. After initialization, send the negotiated `MCP-Protocol-Version` header. The endpoint returns JSON, creates no transport sessions, and does not offer a GET event stream. Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`; initialized and cancelled notifications return an empty 202 response. Unknown tools, unexpected arguments, and apps outside the key's scope are rejected before analytics queries.

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-assistant","version":"1.0"}}}
```

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_stats","arguments":{"app_id":"YOUR_APP_ID","days":30}}}
```

## Share analytics with a colleague

Open **Équipe**, create a viewer invitation for their email, and select the apps. Share the secret invitation link yourself; Submetry does not send email. The link expires after seven days and is displayed only at creation. Its token is carried in the URL fragment, which is not sent in ordinary page requests.

The recipient signs in or registers with the invited email, then accepts the invitation. Matching an email alone never grants access. Acceptance requires the secret invitation token and binds the membership to that account. Readers can consult and export the selected apps' analytics; owners retain settings and access management. Revoking a member removes access immediately. A lost or expired invitation can be revoked and recreated.
