MCP servers

Server SDKs

Add analytics to an MCP server in TypeScript, Python, Go, Rust, C#, Java or Swift with one line.

The MCP SDKs record every request your server handles: tool calls with their duration and errors, tools/list and the other methods, which client sent them (Claude, Cursor, ChatGPT…), the session, and the tool list each time it changes. Any transport works, stdio included.

Add an MCP server

Open Project settings → Setup → MCP servers and add a server (or tick MCP server when you create the project). Each server has its own secret key (al_srv_…), shown on its card there.

.env
AGENTSTATS_MCP_KEY=al_srv_…

Wrap your server

// npm i @agentstats/mcp
import { withAgentStats } from '@agentstats/mcp'

const server = new McpServer({ name: 'my-server', version: '1.0.0' })
withAgentStats(server)

Check the dashboard

Connect a client and call a tool. The server's card on Setup says Receiving within a few seconds, and the call shows up on the Overview and the server's Tools page.

Supported libraries

LanguageLibraries
TypeScript@modelcontextprotocol/sdk and anything built on it
Pythonmcp 1.x and 2.x (Server, FastMCP, MCPServer), fastmcp 2.x to 4.x
Gomodelcontextprotocol/go-sdk, mark3labs/mcp-go
Rustrmcp
C#ModelContextProtocol
Javaio.modelcontextprotocol.sdk, Spring AI tool specifications

On Java the SDK wraps tool specifications rather than the transport, so it records tool calls and the tool list but not tools/list or initialize timings.

What is sent

Per request: method, tool name, duration, success or error, what failed (the tool itself, or the protocol with its JSON-RPC code), the error message (first 300 characters), how many characters of text a successful result handed the model, client name and version, and a session id. Once per change: the tool list (names, descriptions, input schemas) and the server's name, version and instructions.

Tool arguments, tool results and resource contents are never sent: a result's size is a count, not its text. Sizes show as each tool's Context cost (tokens its definition and its results add to the agent's context).

Only tool calls, resource reads and prompt gets count toward your plan's events. initialize, the tool, resource and prompt listings and sign-in are recorded and shown but not billed.

Performance

Recording a call is a timestamp and an append to an in-memory buffer, measured at well under a microsecond in TypeScript and Go and a few microseconds in Python. A background worker sends batches every 2 seconds or every 250 events with a 5-second timeout. If AgentStats is slow or unreachable, batches are dropped and counted, never retried on your request path, and nothing is raised into your server. The buffer holds 10,000 events and drops the oldest when full.

Options

apiKey
string
The server key. Defaults to AGENTSTATS_MCP_KEY. Without a key the SDK does nothing.
serverName
string
Defaults to the name your server reports.
sampleRate
number
Share of tools/call requests to record, 0–1. Default 1.
captureErrors
boolean | (error) => string | null
What to send of a failed request's message, cut at 300 characters. true (default) sends it, false sends none (the request still counts as failed), and a function gets { tool, method, message, code } and returns the text to keep, or null for none. See Error messages.
captureCatalog
boolean
Send the tool list. Default true.
feedbackTool
boolean
Add a send_feedback tool to your server's tools. Default false. See Feedback.

Feedback

Turn on the feedback tool and the SDK adds a send_feedback tool to your server's tool list and answers it itself: calls never reach your handlers. Agents call it when a tool fails them or can't do what the user needs, and users can ask their agent to pass something on. Each report shows on the server's Feedback page with the tool it's about, the client and the session, and is emailed and sent to webhooks (mcp.feedback) as your notification settings say.

withAgentStats(server, { feedbackTool: true })

The text is written by the agent, so the tool asks it to leave out personal information and secrets. If your server has its own send_feedback, the SDK leaves it alone.

Sign-in (OAuth)

When your server asks clients to sign in (MCP authorization), the SDK records which client app each session signed in with and the scopes it was granted, from the token your auth layer validated. It never reads or sends the token, the user it belongs to or its expiry.

  • The client app is kept only when its client id is a Client ID Metadata Document URL, the app's public identity (for example claude.ai/oauth/mcp-client-metadata.json). A client id from Dynamic Client Registration is random per installation, so it's recorded as registered.
  • Scopes are kept as names, up to 20.
LanguageWhere the SDK reads it
TypeScriptauthInfo from requireBearerAuth (on req.auth)
Pythonthe MCP SDK's access token (AccessToken.client_id, scopes)
Gogo-sdk TokenInfo (Scopes, and Extra["client_id"]); mcp-go: Options.AuthInfo
RustAuthInfo your auth layer inserts into the request extensions, or auth_info_with
C#the request's ClaimsPrincipal (client_id, azp or cid; scope or scp), or AuthInfo
Swiftawait transport.signedIn(clientID:scopes:) after your HTTP layer verifies the token
JavaauthInfo(exchange -> …)

The overview's Sign-in card shows signed-in sessions, sign-ins started, rejected tokens and missing scopes, by client app.

Error messages

Arguments, results and resource contents are never sent. Error messages are, because they're what explains a failure, but they can carry data too. A database tool's error often contains the values that failed, as in duplicate key value violates unique constraint "users_email_key" followed by Key (email)=([email protected]) already exists. Decide per tool what to keep:

withAgentStats(server, {
  captureErrors: ({ tool, message }) => {
    if (tool === 'run_sql') return message.split('\n')[0].replace(/\(.*?\)=\(.*?\)/g, '(…)=(…)')
    if (tool === 'read_secret') return null // count the failure, keep no text
    return message
  },
})

The function runs as the response is sent, so keep it cheap. If it throws, nothing is kept and the request is unaffected. The other SDKs take a function too: Python capture_errors=fn, Go Options.ErrorText, Rust Options::capture_errors_with, Java .captureErrors(fn), .NET ErrorText and Swift errorText:. Each gets the same four fields, and in Go also the error the handler returned, for errors.As.

To stop keeping messages without a deploy, turn off Keep error messages on the server's card under Project settings → Setup. The server then drops them on arrival, from the SDK and the proxy alike.

Set AGENTSTATS_DISABLED=1 to turn the SDK off and AGENTSTATS_DEBUG=1 to log what it does. In serverless handlers, call flush() before returning.