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 statusMCP 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.
Related MCP server: Trae MCP Monitor
Two packages, one job each:
Package | Who uses it | What it does |
MCP server authors | Import it, call | |
Agent users | An MCP server you register once. Exposes |
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.
mcp-telemetry-sdk)npm install mcp-telemetry-sdkimport { 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.
mcp-telemetry-server)npm install -g mcp-telemetry-serverRegister 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.
mcp-telemetry-sdknew 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.
| Emits | Notes |
|
| Call once, at the beginning of the tool handler. |
|
|
|
|
|
|
|
| |
|
|
|
|
|
|
|
| Async. This is the terminal event — nothing else may be sent after it, so it actively retries delivery for up to 1.5s instead of relying on a future |
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-serverExposes three MCP tools:
Tool | Behavior |
| Blocks and streams live |
| Lists all jobs the server currently knows about, with status and cost. |
| Full state of one job — every step, cost, and any failure reason. |
Three genuinely different categories of approach exist near this space — none of them solve the same problem:
mcp-telemetry | Async job runners | Completion notifiers | OpenTelemetry MCP instrumentation | |
Mechanism | Push ( | Poll (call a status/tail tool yourself) | Push, but only at completion (webhook/sound) | Traces/metrics to an observability backend |
Live step-by-step progress | Yes | No — you ask, it answers | No — only "it's done" | No — post-hoc analysis |
Watch from a different session | Yes | No — tied to the session that started it | Partial (a webhook can fire anywhere) | N/A — not agent-facing |
Who it's for | Any MCP server author + any agent | Anyone needing async shell execution specifically | Anyone wanting a completion ping | Server operators monitoring their own deployment |
Relationship to SEP-1686 (MCP Tasks): the MCP spec's own answer to this problem — Accepted into the spec (not just proposed), giving requests a durable task handle (taskId) with tasks/get polling and a progressToken valid for the task's whole lifetime. It's the eventual "correct" fix, backed by real production cases (Amazon cites healthcare data pipelines, CI/CD wrapping, and multi-agent systems in the SEP itself). The catch: it's labeled awaiting-sdk-change — the standard is settled, but client/server SDKs haven't implemented it yet, so it isn't something you can rely on today. mcp-telemetry solves the same problem now, on the current stable protocol — a working bridge you can adopt today and retire once Tasks lands in the SDKs you depend on, not a competing standard.
The producer→server connection is a persistent, queued socket, not one connection per event. Events are flushed in order once connected; a burst that arrives before the connection finishes establishing is queued and delivered in order once it does.
Delivery is best-effort, not guaranteed, with one exception: done(). Every other event silently drops if the collector isn't reachable and nothing else triggers a retry — this is deliberate (telemetry should never be able to block or crash your actual tool call). done() is the one event that actively retries for a bounded window, since it's usually the last thing a job ever sends.
telemetry_subscribe only shows live-forward events — it doesn't replay history. If a job already finished before you subscribed, use telemetry_job_status instead.
This is not a distributed job queue. There's no persistence across a collector restart, no cross-machine delivery, and no retry policy beyond what's described above. If you need that, you want a real message queue — this is deliberately just enough to solve "watch a local MCP tool call live," nothing more.
git clone https://github.com/arnavranjan005/mcp-telemetry.git
cd mcp-telemetry
npm install
npm run build
npm testSee CONTRIBUTING.md for the full setup, monorepo layout, and PR expectations.
List all active and recently completed jobs across all connected MCP servers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It specifies scope (all servers, active and recently completed) but lacks details on output format, pagination, or rate limits. Adequate for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded with key action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema provided, and description does not specify what fields the returned jobs contain. Minimal completeness for a simple listing tool, but could be improved by describing output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description correctly adds no additional parameter information, aligning with baseline expectation for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all active and recently completed jobs across all connected MCP servers. It distinguishes itself from siblings 'telemetry_job_status' (specific job status) and 'telemetry_subscribe' (subscription).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Usage is implied by the sibling names but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full status of a specific job — all steps, cost, and any failure reason.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Job ID returned by job_start event or telemetry_jobs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It mentions what is returned (steps, cost, failure reason) but does not disclose read-only nature, error behavior, or permission requirements. Basic but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear, concise sentence with no wasted words. Information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema, no annotations), the description is largely complete. It covers the key output elements. Minor gap: no mention of synchronous/asynchronous behavior or error handling, but acceptable for simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema description for jobId is already informative. The tool description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get status), resource (specific job), and what is included (full status: steps, cost, failure reason). It distinguishes from sibling tools by implying this is for a specific job, while telemetry_jobs likely lists jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (to get full status of a specific job) but does not explicitly state when not to use or provide alternatives beyond the sibling list. The context suggests it is for individual job status, not listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Watch live job events as they happen — blocks and streams inline progress until the job (or, with no jobId, the next job) finishes, or until timeoutMs elapses.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | No | Watch only this job. Omit to watch the next job to start. | |
| timeoutMs | No | Give up and return after this many ms. Default 5 minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses blocking nature ('blocks and streams inline progress'), behavior with/without jobId, and timeout limit. With no annotations, description adequately conveys the streaming and blocking behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently packs purpose, blocking behavior, conditional logic, and timeout. Could be slightly more structured but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains core behavior but lacks details on event format, stop mechanisms beyond timeout, or output expectations. Without output schema, more context on return format would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers both parameters well (100% coverage). Description adds minimal new meaning beyond 'omit to watch next job' which is redundant with schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Watch live job events as they happen' with specific verb and resource. Distinguishes from siblings telemetry_jobs (list) and telemetry_job_status (status check) by focusing on real-time streaming.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for live monitoring but does not explicitly state when to use vs alternatives like telemetry_job_status for one-time checks. No when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: listing jobs, getting detailed status of a specific job, and subscribing to live events. There is no overlap or ambiguity between them.
All tools share the 'telemetry_' prefix, but the naming patterns mix plural noun ('telemetry_jobs'), singular noun phrase ('telemetry_job_status'), and verb ('telemetry_subscribe'). This minor inconsistency prevents a perfect score.
With 3 tools, the server is slightly on the lean side but still provides the essential functions for monitoring telemetry jobs: list, detail, and subscribe. It feels appropriate for its focused scope.
The tool set covers the core workflows of viewing active/recent jobs, getting detailed status, and watching live progress. Minor gaps exist, such as lacking filtering or job management capabilities, but these are reasonable omissions for a simple monitoring server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Intelligence subscription protocol for AI agents. Scored, filtered AI intelligence signals via MCP.
Free MCP window into a live autonomous machine-economy experiment: telemetry, hypothesis scoreboard.
Hosted MCP messaging across owners, tools, and machines, with readable transcripts.
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/arnavranjan005/mcp-telemetry'
If you have feedback or need assistance with the MCP directory API, please join our Discord server