SubmetryDocumentationSet up your app →

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:

[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.

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.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-assistant","version":"1.0"}}}
{"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.