A CLI debugging and testing toolkit for AI agent developers who build on MCP. Record every tool call, inspect traces, diff runs, replay deterministically, and assert in CI — no code changes required.
Your agent makes dozens of tool calls per session. When something goes wrong you need to see exactly what was sent, what came back, and how long it took. mcpx gives you that visibility in five commands.
Transparent proxy captures every tools/call as an NDJSON trace file. Works with HTTP and stdio MCP servers.
Call timeline with latency, retries detection, error flagging, and warnings — all in your terminal.
Serve recorded responses from a trace file. Identical behavior every run — no API keys, no network.
Compare two trace files side by side. Catch which tool calls were added, removed, or changed between runs.
Write YAML assertion rules and run them against any trace. CI-friendly exit codes.
Install globally or run with npx — no config required.
| Command | Description |
|---|---|
| mcpx record | Record tool calls between your agent and an MCP server |
| mcpx inspect | Analyze a trace file — timeline, latency, warnings |
| mcpx replay | Serve recorded responses from a trace file |
| mcpx diff | Compare two trace files, highlight changes |
| mcpx assert | Run YAML assertion rules against a trace (CI-friendly) |
| Flag | Description |
|---|---|
| --target <url> | URL of an HTTP-based MCP server to proxy |
| --stdio <command> | Command to start a stdio-based MCP server |
| --port <n> | Proxy port (default: 4111, auto-detects free port) |
| --out <file> | Output trace file path (default: timestamped filename) |
| Flag | Description |
|---|---|
| --trace <file> | Path to the NDJSON trace file |
| --verbose | Show full JSON payloads for each call |
| --step-threshold <n> | Warn when step count exceeds this value |
| --latency-threshold <ms> | Warn when call latency exceeds this value |
Real workflows showing how mcpx fits into your agent development cycle.
Start a recording session against any MCP server. Here we use the alpaca-mcp-server (paper trading) via stdio transport.
Starting stdio server: uvx alpaca-mcp-server
Connected to: Alpaca MCP Server v3.1.1
mcpx record
Proxy: http://localhost:4111/mcp
Target: uvx alpaca-mcp-server
Trace: alpaca-trace.ndjson
Waiting for connections... (Ctrl+C to stop)
http://localhost:4111/mcp and make tool calls. Everything is recorded transparently. Hit Ctrl+C when done.Now inspect the recorded trace:
mcpx inspect
Session: 9bdca698-4499-45eb-b4fe-8069610437f5
Target: uvx alpaca-mcp-server
Recorded: 2026-03-28T19:52:28.330Z
Duration: 230.5s
Calls: 6 total, 5 unique tools
-------------------------------------------------------
# Tool Latency Status
1 get_account_info 234ms ok
2 get_stock_bars n/a pending
3 get_clock 81ms ok
4 get_orders 97ms ok
5 get_account_info n/a pending RETRY
-------------------------------------------------------
Warnings (1):
! Retry: get_account_info called 2x with identical arguments
Summary: 6 calls, 0 errors, 1 warnings
mcpx inspect automatically detects retries (same tool + same arguments called multiple times), high latency, and error responses. Use --verbose to see full request/response payloads.Serve recorded responses from a trace file. Your agent sees identical behavior every time — no API keys, no network, no rate limits.
Server: http://localhost:4111/mcp
Trace: alpaca-trace.ndjson
Calls: 6 recorded responses loaded
Serving replay... (Ctrl+C to stop)
Now send the same tool call and get the exact recorded response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{
"type": "text",
"text": "{"is_open":false,"next_close":"2026-03-30T16:00:00-04:00",...}"
}],
"isError": false
}
}
Compare two traces to see what changed. Did the agent start making extra calls? Did a tool response change? Diff tells you.
mcpx diff
Before: trace-before.ndjson (4 calls)
After: trace-after.ndjson (5 calls)
-------------------------------------------------------
get_account_info
~ get_stock_bars arguments changed
get_clock
+ get_positions added
get_orders
-------------------------------------------------------
Summary: 1 added, 0 removed, 1 changed, 3 unchanged
Write YAML rules that define what a "good" trace looks like. Run them in CI to catch regressions automatically.
rules.yaml
Trace: alpaca-trace.ndjson
Rules: rules.yaml
-------------------------------------------------------
[PASS] tool_called: get_account_info
[PASS] tool_called: get_clock
[PASS] tool_order: get_account_info > get_stock_bars > get_orders
[PASS] no_errors: true
[PASS] no_retries: true
[PASS] max_steps: 10
[PASS] max_latency: 5000
[PASS] tool_called_times: get_account_info = 1
[PASS] tool_called_with: get_stock_bars
9 passed, 0 failed (9 total)
mcpx assert to your CI pipeline to enforce agent behavior contracts.All available rule types for mcpx assert.
| Rule | Value | Description |
|---|---|---|
| tool_called | string | Assert a tool was called at least once |
| tool_not_called | string | Assert a tool was never called |
| tool_order | string[] | Assert tools were called in this order |
| tool_called_times | {tool, times} | Assert exact call count for a tool |
| tool_called_with | {tool, args} | Assert a tool was called with specific arguments |
| max_steps | number | Assert total calls don't exceed a limit |
| min_steps | number | Assert at least this many calls were made |
| no_errors | true | Assert no tool calls returned errors |
| no_retries | true | Assert no duplicate calls with identical arguments |
| max_latency | number (ms) | Assert no call exceeds this latency |
Traces are NDJSON files (one JSON object per line). The first line is session metadata; every subsequent line is a trace event. You can process them with any tool that reads JSON — jq, Python, your own scripts.
Example trace file
| Field | Description |
|---|---|
| step | Auto-incrementing counter per tool call |
| callId | JSON-RPC id — links request to response |
| tool | Tool name (e.g., get_stock_bars) |
| eventType | request, response, or error |
| latencyMs | Time between request and response (on response events) |
| input / output | Tool arguments (request) or result payload (response) |
mcpx is a transparent HTTP reverse proxy with JSON-RPC awareness. It doesn't re-register tools or modify messages — it just observes.
HTTP transport: mcpx forwards requests to the target URL using native fetch. It handles both JSON and SSE responses, tapping the stream without buffering.
Stdio transport: mcpx spawns the MCP server as a child process and connects via the SDK's StdioClientTransport. The agent still talks HTTP to the proxy.
Only tools/call is traced: Protocol messages (initialize, tools/list, notifications) pass through but aren't recorded. The trace captures what matters: which tools were called, with what arguments, and what came back.
Add mcpx to your agent workflow and get full visibility into every tool call. Test deterministically. Catch regressions in CI.
npx @turingspark/mcp-tracer record --stdio "your-mcp-server"