MCP connector

Put your Kometrics data inside Claude, ChatGPT or any MCP client, over OAuth or an API key.

Kometrics speaks the Model Context Protocol, the open protocol AI assistants use to reach outside tools. Add the connector once and you can ask about your MRR, churn, cohorts and customers inside the assistant you already have open, with a link back to the report every figure came from.

The endpoint is https://app.kometrics.com/mcp. It is the same one for every client and every workspace.

Everything the connector exposes is read only, and it is scoped to one workspace. There is no tool that writes, so nothing an assistant does through it can change your billing data, your settings or your account.

claude mcp add --transport http kometrics https://app.kometrics.com/mcp \
  --header "Authorization: Bearer ko_your_api_key"

Adding it to Claude

Open Settings, then Connectors, then Add custom connector.
Paste https://app.kometrics.com/mcp as the URL and save.
Claude sends you to Kometrics to sign in, approve the connection and pick the workspace it reads. Approve it, and you land back in Claude with the connector live.

There is nothing to copy and paste in between: Claude registers itself with our authorization server, so you never handle a client id, a secret or a token.

Adding it to ChatGPT

Turn on Developer mode under Settings, then Connectors.
Add a connector with the same URL, https://app.kometrics.com/mcp, and OAuth as the authentication.
Approve it on the Kometrics screen, choosing the workspace it reads.

Connecting with an API key instead

Clients that let you set a header (Claude Code, most terminal clients, anything you write yourself) can skip OAuth and send a workspace API key as a bearer token, exactly as the REST API takes it. A key is scoped to one workspace, so the connector serves that one.

Create the key under Settings, then API keys. Revoking it there cuts the connector off with it.

curl https://app.kometrics.com/mcp \
  -H "Authorization: Bearer ko_your_api_key" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Choosing the workspace

A connector reads one workspace. With OAuth you choose which one on the approval screen, so there is nothing to paste and nothing to look up. With an API key it is whichever workspace the key belongs to.

The choice is per assistant, which is what lets Claude read one book while ChatGPT reads another on the same account. Change it any time under Settings, API, and it applies to the next question that assistant asks.

To reach two workspaces from the same assistant, add the connector twice with the id on the URL: https://app.kometrics.com/mcp?workspace=<id>. A URL that names a workspace always wins over the one chosen at approval.

The workspace is fixed before any conversation starts, and never by the assistant. There is no tool argument that can name a workspace, so no conversation and no instruction hidden in your data can move a connector onto a different book.

What it can answer

The connector exposes the same nine tools Kometrics AI runs against, computed by the same code as the reports, so an answer given in Claude and the same answer given in Kometrics cannot disagree.

Tool	What it returns
report_series	Any metric over a date window: MRR, ARR, churn rates, subscribers, ARPA, LTV, movements.
movement_list	The individual customer movements behind a number: who churned, expanded or signed up.
past_due_summary	MRR sitting on customers in dunning, and the customers carrying it.
customer_search	Find customers by name, email or id, or list the book ranked by MRR.
customer_detail	One customer: MRR, status, subscriptions, recent movements and invoices.
cohort_retention	Retention by signup cohort, by customers or by MRR.
forecast_baseline	The growth, expansion and churn rates off recent closed months, and the projection.
upcoming_renewals	Cash expected from renewals in the next 30, 60 or 90 days.
risk_radar	Customers whose MRR is at risk right now, and why.

Protocol notes

The server implements the 2026-07-28 revision, which is stateless: there is no handshake and no session, and every request carries its own protocol version, client identity and capabilities. It also answers the handshake-based revisions back to 2025-03-26, so a client that has not moved yet still connects.

Authorization follows the MCP spec: an unauthenticated request gets a 401 whose WWW-Authenticate header points at our protected resource metadata, and the client takes it from there.

Behaviour	Response
No token, or a token we did not issue	401 with the `WWW-Authenticate` challenge.
A workspace the account cannot reach	403.
A protocol version we do not speak	400 with code -32022 and the versions we do.
Headers that disagree with the body	400 with code -32020.
A method we do not implement	404 with code -32601.
GET or DELETE on the endpoint	405. Both were removed in this revision.

A workspace past the free $1,000 MRR threshold without an active plan keeps the MRR chart and nothing else, the same rule the app screens follow. The tools stay listed and say so when called.

{
  "resource": "https://app.kometrics.com/mcp",
  "authorization_servers": ["https://<project>.supabase.co/auth/v1"],
  "scopes_supported": ["openid", "email", "profile"],
  "bearer_methods_supported": ["header"]
}