MCP server & CLI

Both the CLI and the MCP server are thin clients of the public API: they use the same POST /v1/query contract 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, and most clients need no configuration at all:

• OAuth (recommended). Add the URL and the client opens a browser window; you sign in with your usual magic link and pick the organisation the app may read. Nothing is pasted anywhere, and you can disconnect the app later under Settings → Connected apps. This works because the server implements 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 refresh silently; 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, opens the consent screen, and you are done. No API key, no 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 hit most last week on demo.test?" The assistant calls list_sites, then query_analytics with include_bots: true, filter bot_category eq ai_crawler, dimension path.

Troubleshooting

• The client keeps asking to authorize. The MCP URL must be the one in the metadata document, https://mcp.metrikstack.com/mcp, 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

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.