# 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](/docs/diagnostic-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](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization): 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**

```sh
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:

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

**VS Code** (`.vscode/mcp.json`):

```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`:

```json
{
  "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:

```toml
[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](#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

| Tool | What it answers |
| --- | --- |
| `get-overview` | Sessions by verdict (Human, AI agent, Unknown; `human`, `agent`, `unknown` in the data), agent minutes, and AI agent calls through your MCP server and API, for the last 1 to 90 days. |
| `list-agent-tools` | Each MCP tool and API route: calls, errors, error rate and response times (p50 and p95 where measured), and the MCP clients agents used. |
| `list-accounts` | Your customer accounts ranked by agent activity: agent minutes plus AI agent calls, per channel, with first and last agent use. `totals.accountsUsingAgents` counts only accounts your server confirmed, as Home does; `totals.sentOnlyByThePage` is the IDs only the page sent. |
| `get-account` | One account (by the account ID your server sent): its agent minutes, calls per channel and client, and the tools and routes it used. |
| `list-stuck-points` | The issues in Issues: where agents failed, were refused or kept retrying (errors), tools and routes whose calls ran past your slow-call limit (slow) and tools whose responses were over your token limit (oversized), ranked by the accounts affected, each with its short issue ID and status. Filter with `category`. |
| `get-issue` | One issue by its short ID (such as `AI-7K2M`): what happened, its category, status, priority, counts, trend, first and last seen, and up to five sample MCP or API session IDs. |
| `get-session` | One MCP or API session by its ID (`mcpsession_…` or `apisession_…`): who drove it and how we know, the account ID, and each call's tool or route, outcome, time, response size and whether it was slow or oversized. Shapes only. |
| `list-tool-suggestions` | Things agents did by hand or tried to call with no approved tool behind them. One your MCP server or API already has says where (`state` `on_mcp_server` or `on_api`, `existsOn`). Nothing there is turned on. |

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