mcp-xray

See what your MCP server actually does.

Your MCP server works in MCP Inspector but breaks once a real agent (Claude, Cursor) drives it in production? That's because Inspector is its own client — it never sees the real data path. mcp-xray does.

It's a tiny proxy you drop in front of your server. It forwards the protocol byte-for-byte (your client never notices) while recording every request, response, JSON-RPC error, silent tool failure, slow call, and retry storm to a log you can actually read.

[17:19:39.256] -> REQ         tools/call [echo]
[17:19:39.257] <- RES         tools/call [echo] (1ms)
[17:19:39.376] -> REQ         tools/call [slow]
[17:19:39.527] <- SLOW        tools/call [slow]  ~ 151ms (threshold 100ms)
[17:19:39.496] -> REQ         tools/call [flaky]
[17:19:39.498] <- SILENT-FAIL tools/call [flaky]  ! upstream timed out
[17:19:39.739] <- RETRY-STORM "flaky" failed 3x within 10s — likely a retry storm burning tokens

Why

The official Inspector is great for local poking, but 40% of deployed MCP servers have at least one broken tool, and the worst failures are silent: a tool returns isError: true inside an otherwise-200-OK response, so it looks fine at the protocol level while the agent quietly gets garbage. mcp-xray is built to catch exactly those.

What it flags

| Signal | Meaning | | --- | --- | | ERROR | A JSON-RPC protocol error came back. | | SILENT-FAIL | A tools/call "succeeded" but returned isError: true — the failure Inspector hides. | | SLOW | A call took longer than the threshold (default 5000ms). | | RETRY-STORM | The same tool failed repeatedly in a short window — the agent is burning tokens retrying. |

Install & use

No install needed — run it via npx. In your MCP client config, replace your server command:

// before
"command": "node",
"args": ["server.js"]

// after
"command": "npx",
"args": ["mcp-xray", "--", "node", "server.js"]

Then use your client normally. Two logs appear in the working directory:

• mcp-xray-<time>.log — human readable
• mcp-xray-<time>.jsonl — one JSON object per event, for your own tooling

Options

| | | | --- | --- | | -h, --help | Show help | | MCP_XRAY_SLOW_MS | Env var: latency (ms) above which a call is flagged SLOW (default 5000) |

See it work in 10 seconds

git clone https://github.com/Thomas-Brade/mcp-xray.git
cd mcp-xray
npm install
npm run demo

The demo runs mcp-xray against a built-in mock server that deliberately includes a slow tool and a failing tool, so you can watch every signal fire.

How it works

mcp-xray spawns your real server as a child process and sits in the stdio path:

client.stdout  ->  mcp-xray stdin   -> [tee] ->  server.stdin
server.stdout  ->  [tee]            ->           mcp-xray stdout -> client.stdin

The raw bytes are forwarded untouched, so the protocol is never altered. A copy of each message is parsed and correlated (request ↔ response by id) to measure latency and classify failures. mcp-xray never writes to stdout — that channel is reserved for the protocol.

Status

Early, but working. Issues and ideas welcome — especially which production failures you've hit that this should catch next.

License

MIT