@turingspark/mcp-tracer

CLI debugging and testing toolkit for AI agent developers who build on the Model Context Protocol (MCP).

mcpx sits as a transparent proxy between your agent and any MCP server, recording every tool call. From that trace it provides instant observability, deterministic replay, and regression testing.

Documentation

Full documentation with examples: turingspark.com/tools/mcp-tracer

Quick Start

npm install -g @turingspark/mcp-tracer

This installs the mcpx command globally.

1. Record

Point the proxy at your MCP server and run your agent:

mcpx record --target http://localhost:3000/mcp

  mcpx record

  Proxy:   http://localhost:4111/mcp
  Target:  http://localhost:3000/mcp
  Trace:   ./trace-2026-03-28-143022.ndjson

  Waiting for connections... (Ctrl+C to stop)

Configure your agent to connect to http://localhost:4111/mcp instead of the real server. All tool calls are recorded to the trace file.

2. Inspect

See exactly what your agent did:

mcpx inspect --trace trace-2026-03-28-143022.ndjson

  mcpx inspect

  Session:   abc-123
  Target:    http://localhost:3000/mcp
  Duration:  1.2s
  Calls:     5 total, 1 errors, 3 unique tools
  -------------------------------------------------------
  #   Tool                      Latency   Status
    1   search_flights             234ms   ok
        -> {"from":"SFO","to":"NYC","date":"2026-04-01"}
    2   search_flights             189ms   ok  RETRY (same args as #1)
        -> {"from":"SFO","to":"NYC","date":"2026-04-01"}
    3   get_flight_details        1204ms   ok
        -> {"flightId":"UA123"}
    4   book_flight                502ms   ERROR
        -> {"flightId":"UA123","passenger":"John"}
        x "Payment method required"
    5   book_flight               3201ms   ok
        -> {"flightId":"UA123","passenger":"John","payment":"card_xxx"}
  -------------------------------------------------------
  Warnings (2):
    Retry: search_flights called 2x with identical arguments (steps 1, 2)
    Error: book_flight returned error (step 4)

  Summary: 5 calls, 1 errors, 2 warnings

3. Replay

Replay recorded responses without a real server:

mcpx replay --trace trace-2026-03-28-143022.ndjson

Your agent gets identical responses from the trace file. No real MCP server needed. Fully deterministic.

CLI Reference

mcpx record

mcpx record --target <url> [--port 4111] [--out trace.ndjson]
mcpx record --stdio <command> [--port 4111] [--out trace.ndjson]

| Flag | Description | Default | |------|-------------|---------| | --target | URL of an HTTP-based MCP server to proxy | - | | --stdio | Command to start a stdio-based MCP server | - | | --port | Port to listen on | 4111 | | --out | Output trace file path | trace-<timestamp>.ndjson |

Provide either --target or --stdio (not both).

mcpx inspect

mcpx inspect --trace <file> [--verbose] [--step-threshold 10] [--latency-threshold 5000]

| Flag | Description | Default | |------|-------------|---------| | --trace | Path to trace file (required) | - | | --verbose | Show full input/output payloads | false | | --step-threshold | Warn when total steps exceed this | 10 | | --latency-threshold | Warn when a call exceeds this (ms) | 5000 |

Built-in warnings:

• Retry detection (same tool + identical args)
• High step count
• High latency
• Error responses
• Unused result (consecutive calls to same tool ignoring previous output)

mcpx replay

mcpx replay --trace <file> [--port 4111]

| Flag | Description | Default | |------|-------------|---------| | --trace | Path to trace file (required) | - | | --port | Port to listen on | 4111 |

Replay uses strict matching: tool name + exact arguments. If the agent sends different arguments than what was recorded, the replay server returns a clear error instead of silently returning wrong data.

mcpx diff

mcpx diff <before.ndjson> <after.ndjson>

Compare two trace files. Shows added, removed, and changed tool calls. Exit code 1 if differences found.

mcpx assert

mcpx assert --trace <file> --rules <rules.yaml>

Run YAML assertion rules against a trace. Exit code 1 if any assertions fail.

| Flag | Description | |------|-------------| | --trace | Path to trace file (required) | | --rules | Path to YAML rules file (required) |

Example rules.yaml:

assert:
  - tool_called: get_account_info
  - tool_order:
      - get_account_info
      - get_stock_bars
  - no_errors: true
  - max_steps: 10
  - max_latency: 5000

Available rules: tool_called, tool_not_called, tool_order, tool_called_times, tool_called_with, max_steps, min_steps, no_errors, no_retries, max_latency. See the full documentation for details.

Trace Format

Traces are NDJSON (newline-delimited JSON). Each line is a self-contained event:

{"type":"meta","traceId":"abc123","targetUrl":"http://localhost:3000/mcp","startedAt":"2026-03-28T14:30:00Z"}
{"step":1,"traceId":"abc123","callId":1,"tool":"search_flights","eventType":"request","direction":"outbound","ts":1700000000,"input":{"from":"SFO","to":"NYC"}}
{"step":1,"traceId":"abc123","callId":1,"tool":"search_flights","eventType":"response","direction":"inbound","ts":1700000234,"latencyMs":234,"output":{"results":3}}

Trace files work with standard tools: grep, jq, diff.

How is this different from MCP Inspector?

| Tool | Focus | |------|-------| | MCP Inspector | Interactive GUI for manually testing MCP servers | | mcp-tracer | Record -> replay -> test agent behavior with tool calls |

mcp-tracer is for agent developers who need determinism, regression testing, and automated analysis of how their agent uses tools.

Feedback

Please send any feedback to team at turingspark.com

License

MIT