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 from cwd

server.tool("deploy", { env: z.string() }, async ({ env }) => {
  const job = telemetry.createJob({ task: `deploy ${env}` });

  job.start();
  job.stepStart("build");
  await runBuild();
  job.stepDone("build", { duration: 2100 });

  job.stepStart("test");
  const passed = await runTests();
  if (!passed) {
    job.stepFailed("test", "3 tests failed");
    await job.done(1);
    return { content: [{ type: "text", text: "Deploy failed at test stage" }] };
  }
  job.stepDone("test");

  await job.done(0);
  return { content: [{ type: "text", text: "Deployed successfully" }] };
});

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)

npm install -g mcp-telemetry-server

Register it as an MCP server, alongside your instrumented one:

{
  "mcpServers": {
    "deploy": { "command": "npx", "args": ["-y", "deploy-mcp"] },
    "telemetry": { "command": "npx", "args": ["-y", "mcp-telemetry-server"] }
  }
}

Then, in your agent session:

You:   deploy to staging
Agent: calls the deploy tool, then telemetry_subscribe with the returned job id

  ▶ deploy staging
  ↻ build
  ✓ build (duration=2100)
  ↻ test
  ✓ test
  ✓ job done (exit 0)

Agent: "Deployed to staging successfully."

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.

getSocketPath(root?) is also exported, for advanced cases where you need to compute the same path a producer and a server will independently derive.

mcp-telemetry-server

Exposes three MCP tools: