mcpspy.dev

how it works

mcp-spy is a transparent proxy. it sits between your AI client (claude, cursor, windsurf…) and the MCP server, intercepting every JSON-RPC message in both directions without changing anything about how either side works.

ai client ────► mcp-spy ────► mcp server
 (claude)      (logs it)      (unchanged)

you don't modify the server. you don't modify the client. you just point the client at mcp-spy's port and watch every request, response, duration, and status code roll in — live, in a TUI, right in your terminal.

it is invisible to both sides. it only observes.

what you get

everything runs on your machine. logs live in a local sqlite database. nothing ever leaves your computer.

• live TUI

  a full-screen terminal UI with every intercepted call — request, response, duration, status. arrow keys to browse, works fully offline.

• works with any MCP server

  filesystem, github, slack, postgres, puppeteer, or one you wrote yourself — wrap any server without touching its code.

• token profiling

  every payload is profiled for token count, so you can see which tool calls are eating your context window.

• auto-redaction

  strip secrets (aws keys, bearer tokens, emails, passwords) from payloads before they touch disk. --redact-pii.

• mock mode

  replay saved responses without a live server (--mock) — deterministic testing, zero api costs.

• CI test runner

  replay saved requests against your server and assert valid responses in github actions. mcp-spy test.

• cURL export

  turn any captured call into a runnable curl command straight from the TUI. press c.

what's shipped & what's next

• zero-config proxy & live TUIshipped

  transparent stdio/http interception with a real-time terminal UI. the core of the whole thing.

• token profilingshipped

  automatic token counts on every request and response, with a session total in the stats bar.

• auto-redaction, mock mode & CI runnershipped

  strip secrets before storage (--redact-pii), return saved responses without a live server (--mock), run regression tests in CI (mcp-spy test).

• session timeline viewwip

  group all tool calls from a single conversation into a chronological timeline — the full context of what the AI was doing, not just payloads in isolation.

• schema diffingsomeday

  warn when your server breaks its own JSON schema response format between calls.