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.

Your MCP server                    mcp-telemetry server         Agent
─────────────────                  ────────────────────         ─────
mcp-telemetry-sdk
  job.stepStart('build')
       │
       │ local socket (queued, persistent connection)
       ▼
  collector receives event
  store updates job state
       │
       │ MCP notifications/progress
       ▼
                                    telemetry_subscribe tool     Claude Code
                                    pushes event to agent   →   sees inline
                                                                 live status

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:

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)

npm install mcp-telemetry-sdk

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { MCPTelemetry } from "mcp-telemetry-sdk";

const server = new McpServer({ name: "my-deploy-server", version: "1.0.0" });
const telemetry = new MCPTelemetry(); // zero config — derives a socket path

... [View full README on GitHub](https://github.com/arnavranjan005/mcp-telemetry#readme)