Other languages MCP Analytics installation

Install and configure the PostHog SDK for your language with your project token. If your language has no SDK, send events with the capture API.

Create one client when the server starts and reuse it.

In your tools/list response, add a context string to each tool's input schema. The agent fills it with the reason for the call. PostHog groups these reasons into the intent clusters on the dashboard.

{
  "name": "search_docs",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "context": {
        "type": "string",
        "description": "Why are you calling this tool? Describe the goal in general terms, and refer to people by role (\"a customer\") rather than by name. Leave out personal and identifying information."
      }
    },
    "required": ["query", "context"]
  }
}

Remove context from the arguments before your MCP framework validates them, if you can. Then you can mark context as required, and agents fill required arguments more reliably than optional ones. If your framework validates first, make context optional, and add it to the schema that the framework validates against. A schema with additionalProperties: false rejects every argument it doesn't list, so calls that include context fail.

Skip any tool that already has an argument named context, because that argument belongs to the tool. Also skip any tool whose root schema uses $ref, oneOf, anyOf, or allOf.

When a call arrives, remove context from the arguments before the handler runs. If its value is a string that isn't blank or "{}", use it as $mcp_intent. See Capturing agent intent for how PostHog uses it.

Every event needs a non-empty $session_id. It groups the calls of one agent conversation, so it must never group calls from different clients. Pick the first case that fits your server:

Don't use credentials, cookies, or client IP addresses as the session. Different clients can share them.

The SDKs derive session IDs with a different hash, so a session served partly by an SDK and partly by your own code splits in two.

Measure each call with a monotonic clock. Capture one event after the handler returns or throws, and don't block the response while it sends. Most PostHog SDKs queue the event and send it in the background. Some send during the capture call. For example, the PHP SDK sends its queue when the queue reaches its batch size. With such an SDK, capture after the response is sent, such as after fastcgi_finish_request() in PHP.

Capture only the final outcome of a call to a tool your server has. Don't capture a $mcp_tool_call for:

• A call that names a tool your server doesn't have. Its name is whatever the agent sent, so it would add fake tools to your tool list.
• A result with resultType: "input_required". Capture the retry that completes the call instead.
• A task handle (resultType: "task"). It isn't a completed call.

This is the event, as PostHog stores it. If you use the capture API, wrap it in the request body that page describes, with your project token:

{
  "event": "$mcp_tool_call",
  "distinct_id": "ses_9f2c4e0b7d1a4c3e8b6f5a2d1c0e9b8a",
  "timestamp": "2026-10-07T14:03:11.204Z",
  "properties": {
    "$mcp_source": "posthog_mcp_analytics",
    "$session_id": "ses_9f2c4e0b7d1a4c3e8b6f5a2d1c0e9b8a",
    "$mcp_server_name": "acme-docs",
    "$mcp_server_version": "1.4.0",
    "$mcp_tool_name": "search_docs",
    "$mcp_resource_name": "search_docs",
    "$mcp_tool_description": "Search the Acme documentation",
    "$mcp_is_error": false,
    "$mcp_duration_ms": 182,
    "$mcp_intent": "Find how to rotate an API key for a customer",
    "$mcp_intent_source": "context_parameter",
    "$mcp_client_name": "claude-code",
    "$mcp_client_version": "2.1.0",
    "$mcp_protocol_version": "2025-11-25",
    "$process_person_profile": false
  }
}

Every $mcp_tool_call needs these properties:

Send these properties whenever you have the value:

Cut names, versions, and header values to 256 characters. The event reference lists every property.

The only nested JSON values are $mcp_parameters and $mcp_response (see the payload step). Keep every other property a string, number, or boolean.

If your server knows who is calling, such as from an OAuth token, set distinct_id to that user's ID. Send person properties as $set and groups as $groups, as described in Identifying users.

Otherwise, set distinct_id to the $session_id and set $process_person_profile to false. That way, anonymous calls don't create person profiles.

A call fails when the handler throws, or when it returns a result with isError: true. For a failed call, set:

Analytics capture must never change what the client receives. Catch every error from your instrumentation code, and return or throw the tool's own failure unchanged.

To see failures in Error Tracking too, capture the exception with your SDK's exception capture. Use the same distinct_id and $process_person_profile as the call event, redact the message, and add the call's $session_id, $mcp_tool_name, and $exception_source: "mcp.tool_call".

Agents and errors put credentials and personal data into text. Before you send $mcp_intent, $mcp_error_message, or an exception message, replace each of these with [redacted]:

• The username and password in a URL (https://user:password@host).
• URL query and fragment values whose name is a credential key (below) or a signature, such as sig, signature, or X-Amz-Signature.
• The value after a credential key in key=value, key: value, or a JSON member such as "password": "hunter2".
• PostHog tokens: ph, a lowercase letter, _, then 20 or more of A-Z, a-z, 0-9, _, or -.
• Email addresses, phone numbers, IP addresses, card numbers, and US social security numbers.

A credential key is one of these names, compared as a whole and ignoring case: authorization, cookie, set-cookie, x-api-key, token, password, secret, or api key, api token, access token, refresh token, client secret, or private key written with _, -, or no separator.

Redact first, then cut the text to its limit.

$mcp_parameters and $mcp_response let you see what agents sent and what your tool returned. For example, you can find calls that succeed but return an empty or wrong result. They can also contain credentials and personal data, so the SDKs redact them before sending. If you capture them, you need to redact them yourself, before you capture:

• Send $mcp_parameters as {"request": {"method": "tools/call", "params": {"name": "<tool>", "arguments": <arguments without context, or {}>}}}, the same shape the SDKs send.
• Send $mcp_response as the tool's result object, with its content blocks and any structuredContent.
• Replace with "[redacted]" the value of every object key that is a credential key.
• Apply the free-text redaction to every string value. A text block often holds a JSON copy of structuredContent, so it can contain the same credentials.
• Replace image and audio content blocks, resource blocks with a blob, and base64 strings of 10 KB or more with a short text placeholder.
• Cut strings to 32,768 characters, arrays and objects to 100 entries, and nesting to 10 levels.

Keep the whole event under 100 KB. If it's still too large, cut the strings in $mcp_response and then $mcp_parameters shorter, and remove the property only when that isn't enough. Never remove a required property or $mcp_error_message.

Without a redaction pass, leave both properties out. All other features work without them.

On revisions before 2026-07-28, a client starts each session with an initialize request. Capture a $mcp_initialize event for it, with the same distinct_id, $session_id, and $process_person_profile as the session's tool calls, plus $mcp_source, $mcp_client_name, $mcp_client_version, $mcp_protocol_version, $mcp_server_name, and $mcp_server_version. The "MCP clients" and "MCP users and sessions" insights in the MCP Analytics dashboard template count these events.

PostHog SDKs batch events. Flush the client when the server shuts down. On serverless and edge platforms, flush at the end of each request without delaying the response, for example with the platform's waitUntil.

Call a few tools through an MCP client, flush, then run this query in SQL insights:

SELECT
    count() AS calls,
    countIf(properties.$mcp_tool_name IS NULL OR properties.$mcp_tool_name = '') AS missing_tool_name,
    countIf(properties.$mcp_server_name IS NULL OR properties.$mcp_server_name = '') AS missing_server_name,
    countIf(properties.$session_id IS NULL OR properties.$session_id = '') AS missing_session_id,
    countIf(JSONType(properties, '$mcp_is_error') != 'Bool') AS bad_is_error,
    countIf(JSONType(properties, '$mcp_duration_ms') NOT IN ('Int64', 'UInt64', 'Double')) AS bad_duration,
    countIf(properties.$mcp_intent IS NOT NULL) AS with_intent
FROM events
WHERE event = '$mcp_tool_call'
    AND properties.$mcp_source = 'posthog_mcp_analytics'
    AND timestamp > now() - INTERVAL 1 HOUR

calls should match the number of calls you made, and every missing_ and bad_ column should be 0. with_intent counts the calls whose agent sent context. If it's 0, check that context appears in your tools/list response.

Then open the MCP Analytics dashboard. Your tools should appear there.