MCP server & CLI

The CLI and the MCP server are small clients of the public API. They send the same POST /v1/query requests as the dashboard.

MCP server

The server speaks MCP over Streamable HTTP at https://mcp.metrikstack.com/mcp. Tools:

Signing in

There are two ways to authenticate. With OAuth, most clients need no configuration:

• OAuth (recommended). Add the URL and the client opens a browser window, where you sign in as usual and pick the organisation the app may read. There is no key to paste, and you can disconnect the app later under Settings → Connected apps. The server follows the MCP authorization spec: it advertises /.well-known/oauth-protected-resource, and the API acts as the authorization server with dynamic client registration and PKCE.
• API key. For clients without OAuth support, or for scripts: create a key under Settings → API keys (scope read is enough) and send it as Authorization: Bearer ak_....

Access tokens last an hour and are refreshed automatically; refresh tokens last 30 days and rotate on every use. OAuth clients get the read scope unless they ask for write, and never admin, so a connector cannot manage keys or members.

Claude.ai and Claude Desktop connectors

In Settings → Connectors → Add custom connector, paste:

https://mcp.metrikstack.com/mcp

Claude registers itself and opens the consent screen. You don't need an API key or headers.

Claude Code

claude mcp add --transport http metrikstack https://mcp.metrikstack.com/mcp

The first tool call opens the browser for consent. With an API key instead:

claude mcp add --transport http metrikstack https://mcp.metrikstack.com/mcp \
  --header "Authorization: Bearer ak_..."

ChatGPT

Enable Developer mode in ChatGPT settings (Connectors → Advanced), then Create connector with the URL https://mcp.metrikstack.com/mcp and authentication OAuth. ChatGPT registers itself and sends you through the same consent screen.

n8n

Use the MCP Client node with:

• Endpoint: https://mcp.metrikstack.com/mcp
• Server Transport: HTTP Streamable
• Authentication: Generic Credential Type → OAuth2 (Authorization Code), or Header Auth with Authorization: Bearer ak_... if you prefer a key.

For OAuth2, register the client once by hand and fill in the endpoints:

curl -X POST https://api.metrikstack.com/oauth/register \
  -H 'content-type: application/json' \
  -d '{"client_name":"n8n","redirect_uris":["https://n8n.example/rest/oauth2-credential/callback"]}'

Generic JSON config (Cursor, Windsurf, other clients)

{
  "mcpServers": {
    "metrikstack": {
      "type": "http",
      "url": "https://mcp.metrikstack.com/mcp"
    }
  }
}

Add "headers": { "Authorization": "Bearer ak_..." } for clients that do not speak OAuth.

Example

Prompt: "Which pages did AI crawlers read most last week on demo.test?" The assistant calls list_sites, then query_analytics with include_bots: true, filter traffic_class eq ai_crawler, dimension path.

Troubleshooting

• The client keeps asking to authorize. Use the MCP URL from the metadata document, https://mcp.metrikstack.com/mcp, and not the API origin.
• 401 with a WWW-Authenticate header. Expected on the first request: it tells the client where to find /.well-known/oauth-protected-resource. A client that cannot follow it needs the API-key fallback.
• Revoking access. Settings → Connected apps disconnects an app immediately; its tokens stop working on the next call.

CLI

Not published yet. There is no download for the CLI yet. Everything it does is also available through the API and the MCP server.

metrikstack login                       # stores API URL + key in ~/.config/metrikstack/config.toml
metrikstack sites list
metrikstack stats demo.test --period 30d
metrikstack stats demo.test --by path --limit 10
metrikstack sources status demo.test
metrikstack sources rotate demo.test server --grace-hours 24
metrikstack tail demo.test              # live events (SSE)

--json prints the raw API response for scripting.