mcpulse

Analytics for MCP servers, for the Python MCP SDK.

One import, one wrap — see which of your tools actually work for the models calling them.

from mcp.server.mcpserver import MCPServer
from mcpulse import watch

mcp = MCPServer("my-server")
watch(mcp, key="mp_live_…")

That is the whole integration. The server is instrumented in place and handed straight back, so the call drops in around an existing server without moving anything else.

Install

pip install mcpulse-sdk

The distribution is mcpulse-sdk; the import stays mcpulse. They differ because mcpulse on PyPI belongs to an unrelated project, and PyPI has no scoping to fall back on the way npm does — so this package mirrors the npm name (@mcpulse/sdk) instead.

No runtime dependencies. mcp is your dependency, not ours.

Options

An empty key turns it off, so a server started without its key configured is silent rather than a source of 401s on every flush.

What leaves your process

Sizes and hashes. Arguments and results do not, and no option turns that on.

Every tool call reports its name, how long it took, how it ended, how many bytes came back, whether the result was empty, and a 12-character one-way hash of the arguments — enough to tell a retry from a fresh call, and not enough to learn anything about either.

The three rules

1. Never throw. Every entry point swallows. If MCPulse fails inside your tool call, your tool fails and you blame us.
2. Never block. Record, buffer, return. Nothing awaits the network on the path a model is waiting on — sending happens on a background thread, never on your event loop.
3. Never store customer data. See above.

Supported

• mcp >= 2.0 — attaches through the supported Server.middleware chain.
• mcp 1.x — falls back to patching the dispatcher's handler map.

Both then wrap your own tool callbacks, which is what lets MCPulse tell a tool that crashed from one whose arguments never validated — the MCP server converts both to isError before anything outside can see the difference.

Cross-language consistency

args_hash is the first 12 hex characters of the SHA-256 of the RFC 8785 canonical form of the arguments. tests/fixtures/canonical.json is the shared conformance suite that every MCPulse SDK runs, so a call hashed here and a call hashed by the TypeScript SDK land in the same bucket.

Licence

MIT