> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentdiscoverability.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the MCP analytics SDK

> See which tools AI agents call on your MCP server. One install, one observe() call.

<Note>
  **Beta.** The TypeScript package is on npm under the `beta` tag. The Python package is not on PyPI yet, and SDK keys are not being issued yet. For early access, email [support@agentdiscoverability.com](mailto:support@agentdiscoverability.com).
</Note>

The SDK runs inside your MCP server and reports each `initialize`, `tools/list` and `tools/call` it handles. It only observes: it never changes your tools, their results or their speed.

## 1. Get an SDK key

Create one on the [MCP page](https://app.agentdiscoverability.com/mcp). It starts with `adok_` and is shown only once. Store it as `MCP_ANALYTICS_SDK_KEY` and never commit it.

## 2. Install

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install @agentdiscoverability/mcp-analytics@beta
  ```

  ```bash Python theme={null}
  pip install agentdiscoverability-mcp-analytics
  ```
</CodeGroup>

## 3. Call `observe()`

Call it once, after your tools are registered and before the server starts.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { observe } from "@agentdiscoverability/mcp-analytics";

  observe(server, { sdkKey: process.env.MCP_ANALYTICS_SDK_KEY! });
  ```

  ```python Python theme={null}
  import os
  from mcp_analytics import observe

  observe(
      server,
      sdk_key=os.environ["MCP_ANALYTICS_SDK_KEY"],
      # Required for now: the Python SDK has no default collector yet.
      collector_url="https://collector.agentdiscoverability.com",
  )
  ```
</CodeGroup>

`server` can be a `Server` or `McpServer` (TypeScript), or a `FastMCP`, `MCPServer` or `Server` (Python). `observe()` never throws. If the key is missing it logs a warning and leaves the server uninstrumented.

## 4. Verify

Connect any MCP client to your server. Within about a minute, the MCP page changes from **Waiting for your first event…** to **Receiving · N events**. You don't need to call a tool first.

To check locally, inspect the handle `observe()` returns. `client.stats()` should show `sent` above zero and `dropped` at zero.

## Requirements

|                | Supported                                                            |
| -------------- | -------------------------------------------------------------------- |
| **TypeScript** | Node ≥ 22, ESM, `@modelcontextprotocol/sdk` ≥ 1.11 and \< 2          |
| **Python**     | Python ≥ 3.10, `mcp` ≥ 1.10 and \< 3, or community `fastmcp` 3.x/4.x |

Not supported: MCP SDK v2 (`@modelcontextprotocol/server`), CommonJS, Bun, Deno, Cloudflare Workers, or `fastmcp` 2.x.

## What is collected

* The tool name, the argument **shape** (key names and types, not values), duration and errors
* The tool result, sanitized and truncated
* The AI client family (Claude, ChatGPT, Cursor…) and versions
* An end-user id only if you supply one. It is hashed before storage.

We never collect conversations, IP addresses, request headers, credentials or argument values. Data is kept for 90 days. See the [Privacy Policy](https://agentdiscoverability.com/privacy).

## Troubleshooting

| Symptom         | Fix                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing arrives | Check the handle's `enabled` is true, `observe()` ran before the server started, a client has connected, and (Python) `collector_url` is set. |
| `401`           | The key is wrong or revoked. Create a new one on the MCP page.                                                                                |
| `413` / `429`   | The batch is too large, or you hit a rate limit. Lower `flushBatchSize` / `flush_batch_size`. The SDK retries `429`s on its own.              |
| `503`           | Ingest is paused on our side. There's nothing to fix.                                                                                         |
| Behind a proxy  | Allow direct HTTPS to `collector.agentdiscoverability.com:443`. Proxies and redirects are refused.                                            |

Still stuck? Email [support@agentdiscoverability.com](mailto:support@agentdiscoverability.com) with your key prefix (never the full key) and the `stats()` output.

## For coding agents

1. Find the file that creates the MCP server and registers tools.
2. Add the dependency, then the `observe()` call from step 3, after the tools are registered.
3. Read the key from `MCP_ANALYTICS_SDK_KEY` and keep it out of git.
4. Change nothing else. No tool name, schema or result may change.
5. Run the server, connect a client, and report the changed file and the `stats()` output.