Ask your own agent about your Telltale data

The analytics MCP server lets you ask Claude, Cursor, VS Code, Codex or any other MCP client about your Telltale data in plain words: "Which accounts used agents most this month?", "Which MCP tools fail most often?", "Where do agents get stuck?".

No coding agent? The same answers are on Home and in Your agent report in the dashboard; this page is for setting up the MCP connection.

It's read-only. It answers with counts, categories and timings for one site, plus the account IDs your own server sent. It can't change anything, and it never returns content.

There are two ways to connect, and both read one site, read-only:

• Sign in from Claude (claude.ai and Claude Desktop custom connectors): no key. Claude opens a Telltale sign-in page and you choose the site.
• An analytics key for Claude Code, Cursor, VS Code, Windsurf, Codex, scripts and any other MCP client.

#Sign in from Claude

1. In Claude, open its settings, go to Connectors and choose Add custom connector.
2. Name it "Telltale analytics" and paste the address: https://app.trytelltale.dev/api/v1/analytics/mcp.
3. Press Connect. A Telltale page opens: sign in if you aren't already, choose the site Claude may read, and press Allow read-only access.

The page shows which app is asking (and the web address that identifies it), where you go back to afterwards, and what it can read. Connecting takes a workspace owner or admin. The connection then shows in Ask your data › Connected apps, where an owner or admin can disconnect it at any time; it stops working at once.

How it works, for your security review:

• Telltale follows the MCP authorization specification, revision 2026-07-28: OAuth 2.1 authorization code with PKCE (S256 only). The server's protected resource metadata is at https://app.trytelltale.dev/.well-known/oauth-protected-resource/api/v1/analytics/mcp and the authorization server metadata at https://app.trytelltale.dev/.well-known/oauth-authorization-server.
• Apps identify themselves with a Client ID Metadata Document (an https address that names the app and its exact return addresses). Dynamic Client Registration is supported for apps that only know it; their names are shown as unconfirmed. Public apps only: there is no client secret.
• Return addresses must match exactly (https, or an app on this computer on any port). Sign-in codes last 60 seconds and work once; a code used twice disconnects what it issued.
• Tokens are for this server only (the resource it was issued for) and have one scope, analytics:read. Access tokens last an hour; refresh tokens last 30 days and change every time they are used. A refresh token used a second time disconnects the connection, because someone else may hold a copy.
• Telltale stores only SHA-256 hashes of codes and tokens. A connection reads the one site chosen when it was allowed. The person who allowed it must still be an owner or admin of that workspace: if their role changes, new tokens are refused at once and the current access token within a minute. Deleting the site removes its connections.
• Allowing, disconnecting and a detected reuse are in the audit log (Settings › Audit log): the app, the site and who did it.
• Apps can also revoke their own connection (https://app.trytelltale.dev/oauth/revoke, RFC 7009).

#Create an analytics key

1. Open Settings › Ask your data › Analytics MCP keys for the site you want to ask about.
2. Choose Create a key, give it a name you'll recognise later (such as "Claude Code on my laptop"), and copy the key. It starts with ao_ak_ and is shown once.

Only workspace owners and admins can create or revoke keys. A site can have up to five. Each key reads one site only: there's no way to name another site or workspace through it. Revoking a key stops it at once. Deleting the site removes its keys.

An analytics key isn't a server key. It can't send events, check rules or read anything outside these tools, and the analytics MCP server doesn't accept your server key or publishable key. Keep it like a password: anyone with the key can read that site's aggregates.

#Connect your client

The server address is https://app.trytelltale.dev/api/v1/analytics/mcp. It uses Streamable HTTP with your key as a bearer token.

Claude Code

claude mcp add --transport http telltale-analytics https://app.trytelltale.dev/api/v1/analytics/mcp --header "Authorization: Bearer ao_ak_..."

Cursor (~/.cursor/mcp.json) and most other clients:

{
  "mcpServers": {
    "telltale-analytics": {
      "url": "https://app.trytelltale.dev/api/v1/analytics/mcp",
      "headers": { "Authorization": "Bearer ao_ak_..." }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "telltale-analytics": {
      "type": "http",
      "url": "https://app.trytelltale.dev/api/v1/analytics/mcp",
      "headers": { "Authorization": "Bearer ao_ak_..." }
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json) names the address serverUrl:

{
  "mcpServers": {
    "telltale-analytics": {
      "serverUrl": "https://app.trytelltale.dev/api/v1/analytics/mcp",
      "headers": { "Authorization": "Bearer ao_ak_..." }
    }
  }
}

Codex (~/.codex/config.toml), with the key in the TELLTALE_ANALYTICS_KEY environment variable:

[mcp_servers.telltale-analytics]
url = "https://app.trytelltale.dev/api/v1/analytics/mcp"
bearer_token_env_var = "TELLTALE_ANALYTICS_KEY"

Claude (claude.ai, Claude Desktop): sign in instead of using a key; see Sign in from Claude.

Put the key in an environment variable or your client's secret store rather than in a file you share.

#The tools

Each tool returns structured content (with an output schema) and the same JSON as text, for clients that read either.

#What it returns, and what it never returns

It returns counts, categories (Human, AI agent, Unknown), timings, tool and route names, page paths as templates, and the account IDs and names your own server sent.

It never returns: what people typed, tool-call arguments or results (Deep insights captures included), the "why" text agents gave, reasons, scores or evidence lists, browser session IDs, IP addresses, user agents, keys or tokens, or anything from another site or workspace. MCP and API session IDs appear only where you would look one up (an issue's sample sessions, and get-session, which answers found: false for an ID from another site).

#Investigate with AI

The dashboard's session drawer (for MCP and API sessions) and issue drawer have an Investigate with AI button. It shows a prompt to copy into your own coding agent, such as "Use the Telltale analytics MCP server to investigate issue AI-7K2M". Your agent then calls get-issue and get-session with your analytics key. Telltale runs no AI for this.

Read the answers the way the dashboard reads them:

• Verdicts are categories, not calibrated probabilities. Unknown is not human: it means there wasn't enough evidence either way.
• "AI agent" is a category of automated driver, not a claim about which model is involved. An agent is named only with how we know it.
• MCP and API callers are agents' clients by definition. A client name such as "Claude Code" is what that client declared about itself.

#Limits

• 120 requests a minute per key. A busy client gets 429 and should wait a moment.
• The server is part of your Telltale origin's server API. It's never served through a public demonstration tunnel.
• Pages that come from a browser on another origin are refused: the server is for MCP clients, not web pages.

#Troubleshooting

• 401 "That is a Site server or publishable key": you pasted the server key. Create an analytics key in Settings › Ask your data.
• 401 "Invalid or revoked analytics key": the key was revoked, its site was deleted, or the header is missing Bearer .
• The client asks you to sign in with OAuth: it didn't send the header. Check the client's header setting, or use the bridge above.
• Numbers differ from the dashboard: check the period. Tools look back from now; the dashboard's periods end at the start of tomorrow (UTC).