mcpscope: The MCP Observability Tool That Finally Lets You Replay Agent Failures
Open SourceScore: 80

mcpscope: The MCP Observability Tool That Finally Lets You Replay Agent Failures

mcpscope is an open-source proxy that records, visualizes, and replays MCP server traffic, turning production failures into reproducible test cases for Claude Code agents.

GAla Smith & AI Research Desk·7h ago·3 min read·4 views·AI-Generated
Share:
Source: dev.tovia devto_mcpSingle Source

The Problem It Solves

When your Claude Code agent using MCP servers behaves unexpectedly, debugging is a nightmare. Tool calls vanish into stderr, you can't see what arguments were actually sent, and there's no way to reproduce the failure. This is the exact gap mcpscope fills—it's an observability and replay testing layer specifically for MCP servers.

How It Works (Install in 2 Minutes)

mcpscope is a transparent proxy written in Go. Install it, point it at your MCP server, and it intercepts every JSON-RPC message without modifying your server code:

go install github.com/td-02/mcp-observer@latest
mcpscope proxy --server ./your-mcp-server --db traces.db

Open http://localhost:4444 and you get a live dashboard showing every tool call, latency percentiles (P50/P95/P99), and error timelines.

For Python MCP servers (common with Claude Code):

mcpscope proxy -- uv run server.py

For HTTP MCP servers:

mcpscope proxy --transport http --upstream-url http://127.0.0.1:8080

The Killer Feature: Replay Testing

This is what changes everything for Claude Code workflows. Once mcpscope records production traces, you can export and replay them in CI:

# Export real production traces
mcpscope export --config ./mcpscope.example.json --output traces.json --limit 200

# Replay in CI — fail on errors or latency regressions
mcpscope replay --input traces.json --fail-on-error --max-latency-ms 500 -- uv run server.py

Now you can: take a session where Claude Code behaved unexpectedly → export the exact MCP traces → turn them into a reproducible test case. No more "it only happens in production."

Catch Schema Drift Before It Breaks Your Agent

Upstream MCP servers changing their tool schemas silently break Claude Code agents. mcpscope's snapshot/diff workflow catches this:

# Capture baseline
mcpscope snapshot --server ./your-mcp-server --output baseline.json
git add baseline.json && git commit -m "chore: add MCP baseline snapshot"

# On every PR:
mcpscope snapshot --server ./your-mcp-server --output current.json
mcpscope diff baseline.json current.json --exit-code

The --exit-code flag makes it CI-friendly—exits non-zero on breaking changes so your PR check fails before the change reaches your Claude Code agent.

Why This Matters for Claude Code Users

MCP is becoming Claude Code's standard way to connect to external tools (32 sources in our knowledge graph show Claude Code uses MCP). But as recent research reveals, 66% of MCP servers have critical security vulnerabilities. mcpscope gives you visibility into what's actually happening between Claude Code and your MCP servers.

Key features in v0.1.0:

  • Live web dashboard with tool call feed and latency views
  • Alerts to Slack/PagerDuty/webhooks
  • OpenTelemetry export (plugs into Grafana/Jaeger)
  • SQLite trace store (local by default, Postgres-ready)
  • Workspace + environment scoping (prod vs staging)
  • Docker + Docker Compose included

MIT licensed, no telemetry, runs air-gapped. Your tool call data stays local.

Try It This Week

If you're using Claude Code with MCP servers (database connectors, API tools, file systems), install mcpscope and run it against your development server for a day. You'll immediately see:

  1. Which tools Claude Code calls most frequently
  2. Latency patterns that might be slowing down your agent
  3. Any errors that were previously hidden in stderr

Then export those traces and add a replay test to your CI pipeline. This is the observability layer MCP has been missing.

AI Analysis

Claude Code users should immediately start using mcpscope for any production MCP workflows. Here's what to do: 1. **Instrument your development environment today**: Run `mcpscope proxy --server ./your-mcp-server` alongside your Claude Code sessions. The dashboard at localhost:4444 will show you exactly what Claude Code is sending to your MCP tools—arguments, timing, errors. This visibility alone will solve many "why did my agent do that?" questions. 2. **Add schema drift checks to your CI**: Use the snapshot/diff workflow shown above. Commit a baseline.json of your MCP server's tool schemas, then run `mcpscope diff` in your CI pipeline. This catches breaking changes from upstream MCP servers before they silently break your Claude Code agent in production. 3. **Build a replay test suite**: Next time Claude Code behaves unexpectedly with an MCP tool, export those traces with `mcpscope export` and save them as test cases. Replay them in CI with `mcpscope replay --fail-on-error`. This turns "production-only" bugs into reproducible, automated tests. This tool directly addresses the AI agent production gap we covered in "The AI Agent Production Gap: Why 86% of Agent Pilots Never Reach Production"—observability and testing are exactly what's missing. mcpscope gives Claude Code users the same testing capabilities they'd expect for any other API integration.
Enjoyed this article?
Share:

Related Articles

More in Open Source

View all