arnavranjan005/mcp-telemetry

**Socket.IO for AI agents.** Instrument any MCP server's tool calls with a few lines, and any MCP client watching (Claude Code, Cursor, or your own tooling) gets live, structured progress — no polling, no context-flooding tool calls.
Why this exists
MCP tool calls are synchronous: an agent calls a tool, waits, gets a result. For anything long-running, that leaves two bad options — block the whole call with no visibility, or have the agent poll a status tool in a loop (which floods the conversation with repeated tool calls and burns context for no new information).
MCP does have one legitimate way for a server to push updates mid-call: notifications/progress, keyed to a progressToken on the in-flight request. But every MCP server author ends up re-implementing the same plumbing — extracting the token, wiring a timer, tailing output, cleaning up on completion. mcp-telemetry is that plumbing, factored out once, plus a companion server so a job started in _one_ session can be watched from a completely different one.
How it fits together
Two packages, one job each:
| Package | Who uses it | What it does |
| ----------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mcp-telemetry-sdk | MCP server authors | Import it, call job.start() / .stepDone() / .log() from your tool handlers. Zero runtime dependencies — it's a socket writer with a persistent, queued connection and nothing else. |
| mcp-telemetry-server | Agent users | An MCP server you register once. Exposes telemetry_subscribe (blocks and streams live progress for a job), plus telemetry_jobs/telemetry_job_status for point-in-time queries. |
These two packages are architecturally independent — the SDK never calls any MCP tool, and the server never imports your tool's code. They only ever meet at a local socket, so a producer with a broken connection can't take down anything, and a collector that's overwhelmed can't block your tool call.
Quickstart
1. Instrument your MCP server (mcp-telemetry-sdk)
That's the entire integration. If nothing is listening on the socket, every call is a fast no-op — your server behaves identically with or without a collector running.
2. Watch it from an agent (mcp-telemetry-server)
Register it as an MCP server, alongside your instrumented one:
Then, in your agent session:
No polling, no separate terminal, no context-flooding tool calls — one deploy call plus one telemetry_subscribe call, regardless of how long the job runs.
API reference
mcp-telemetry-sdk
**new MCPTelemetry(opts?)**
Creates a telemetry client. opts.socketPath overrides the default (derived from process.cwd() via getSocketPath()). Owns one persistent, queued connection shared by every job it creates.
**telemetry.createJob({ id?, task }) → JobHandle**
Starts tracking a job. id defaults to an auto-incrementing job-N.
**telemetry.disconnect()**
Closes the underlying connection. Call on server shutdown if you want a clean teardown instead of letting it idle.
| JobHandle method | Emits | Notes |
| --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start() | job_start | Call once, at the beginning of the tool handler. |
| stepStart(name, meta?) | step_start | name is any string — 'build', 'implement', whatever fits your domain. |