MCP-Spy Docs

The Model Context Protocol (MCP) is the standard that lets AI assistants like Claude call external tools — reading files, querying databases, searching the web, running code, and much more. Every time Claude uses a tool, it sends a structured message behind the scenes. MCP-Spy lets you see those messages.

Think of it like browser DevTools, but for AI tool calls. You see the exact request the AI made, the exact response it got back, how long it took, and whether it succeeded or failed. No guessing, no black boxes.

MCP-Spy is useful in three different situations, even if you have never written a line of code in your life.

MCP-Spy is a transparent proxy. It sits between your AI client (Claude, Cursor, etc.) and the MCP server, intercepting every message in both directions without changing anything about how either side works.

You do not need to modify the MCP server. You do not need to change the AI client. You just insert MCP-Spy in the middle by telling your AI client to talk to MCP-Spy's port instead of the server's port directly.

MCP-Spy is invisible to both sides. It only observes.

No installation needed. Run MCP-Spy with npx directly:

npx mcp-spy --target 3000

This starts MCP-Spy on port 4000 (its default listen port) and forwards traffic to port 3000 where your MCP server is running. Then tell your AI client to connect to http://localhost:4000 instead.

• 1
  Your MCP server is already running on some port (e.g. 3000).
• 2
  Run npx mcp-spy --target 3000 in your terminal. MCP-Spy starts listening on 4000.
• 3
  Update your AI client config to point to http://localhost:4000 instead of 3000.
• 4
  The TUI opens in your terminal. Every tool call appears in real time — request, response, duration, status code.

You do not need to build an MCP server to use MCP-Spy. It works with any existing MCP server — including all the popular ones that the community and Anthropic provide out of the box.

Common examples include the filesystem MCP (lets Claude read and write your local files), the GitHub MCP (lets Claude interact with your repos), the Slack MCP (lets Claude read and send messages), and many others.

Example: Wrapping the Filesystem MCP

Normally your claude_desktop_config.json might look like this:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

To add MCP-Spy, you wrap that command with mcp-spy --target, but since this MCP uses stdio (not HTTP), you use the --wrap mode by passing the original command as the target:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "mcp-spy",
        "--target", "3000",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"
      ]
    }
  }
}

MCP-Spy starts the real MCP server as a child process and intercepts all stdio communication. Nothing changes for Claude — it still gets the same responses, but now you can see every call.

Other popular MCP servers you can wrap

Any MCP server that follows the standard protocol can be wrapped with MCP-Spy — these are just the most common ones.

MCP failures can be confusing because the AI assistant usually gives a vague error message. Here is how to use MCP-Spy to diagnose the most common problems.

If you are developing an MCP server, MCP-Spy is even more valuable. You get live feedback on every tool call during development without adding any logging code to your server.

The setup is the same — run your server, start MCP-Spy pointing at it, and connect your AI client to MCP-Spy's port. As you make changes to your server, MCP-Spy keeps logging. No restarts needed.

Language-specific examples are below in the Server Examples section.

Claude Desktop reads its MCP server config from claude_desktop_config.json. The file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

To spy on any MCP server in Claude Desktop, change its command and args to go through MCP-Spy. Here is a complete example wrapping an HTTP-based custom server:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcp-spy", "--target", "3000"],
      "env": {}
    }
  }
}

Claude Desktop launches this command when it starts. MCP-Spy listens on port 4000, forwards to your server on 3000, and logs everything. Restart Claude Desktop after editing the config file.

Go to Cursor Settings → Features → MCP and add a new server entry. Set the command to launch MCP-Spy instead of your server directly.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcp-spy", "--target", "3000"]
    }
  }
}

Cursor will launch MCP-Spy on startup and route all tool calls through it.

Windsurf (by Codeium) also supports MCP servers. Edit the ~/.codeium/windsurf/mcp_config.json file and add MCP-Spy as a wrapper the same way as Claude Desktop.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcp-spy", "--target", "3000"]
    }
  }
}

Any MCP-compatible client works with MCP-Spy as long as you can configure it to use a custom server address. The pattern is always the same:

1. Find where the client defines its MCP server (usually a JSON config file)
2. Replace the direct server command or URL with MCP-Spy's address (http://localhost:4000)
3. Make sure MCP-Spy is running with --target pointing at the original server

Compatible clients include: Claude Desktop, Cursor, Windsurf, VS Code (Continue extension), Zed, and any custom application using the official MCP SDK.

Edit & Replay lets you take any logged request, modify its JSON payload in the browser, and resend it to your locally running MCP server — without triggering Claude again.

This is useful for:

• Testing how your server handles edge cases (empty strings, large numbers, missing fields)
• Reproducing a specific failure with slightly different inputs
• Confirming that a bug is in the request (Claude's side) vs. the response (server side)

Any log entry in your dashboard can be turned into a permanent, public link that anyone can view — no login required.

The shared trace page shows the full request and response payloads with syntax highlighting, the HTTP method, status code, and duration. It is read-only and works from any device.

Add --redact-pii to automatically mask secrets from all payloads before they are saved locally or synced to the cloud. Nothing sensitive ever touches the database.

npx mcp-spy --target 3000 --redact-pii --sync YOUR_KEY

The following patterns are automatically redacted:

Redacted logs are tagged with a 🔒 badge in both the TUI and dashboard. The original bytes are forwarded to the MCP server unmodified — redaction only affects storage.

Every intercepted request and response is automatically profiled for token count. This tells you how much of an LLM's context window each tool call consumes — and gives you a rough cost estimate.

Token counts appear as ~1.2k badges on every log row in the TUI and dashboard. The TUI stats bar shows the session total. No extra flags needed — it's always on.

Turn any saved log into a runnable shell command or a Postman collection with one click.

curl -s -X POST http://localhost:4000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call",...}'

Add --mock to make MCP-Spy intercept all requests and return saved responses from your local database — without forwarding anything to the real server.

npx mcp-spy --target 3000 --mock

For each incoming method (e.g. tools/call), MCP-Spy looks up the most recent successful response for that method in SQLite and returns it immediately. If no saved response exists for a method, it returns a 404 JSON-RPC error.

Use the test subcommand to replay saved requests against your MCP server and assert valid JSON-RPC responses. Exits 0 on all pass, 1 on any failure — works natively in GitHub Actions, GitLab CI, and any shell pipeline.

# Replay last 10 saved requests against the server on port 3000
npx mcp-spy test --target 3000

# Only replay a specific method
npx mcp-spy test --target 3000 --method tools/call

# Only replay from a specific server label
npx mcp-spy test --target 3000 --name filesystem --count 20

name: MCP Server Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Start MCP server
        run: node server.js &
      - name: Run MCP-Spy tests
        run: npx mcp-spy test --target 3000 --count 20

How to launch the TUI

The Terminal UI (TUI) is a full-screen interface that shows a live list of intercepted MCP calls on the left and the selected payload on the right. It opens automatically whenever you start the proxy with a --target port.

# Basic — proxy + TUI in one command
npx mcp-spy -t 3001

# With a label and cloud sync (Pro)
npx mcp-spy -t 3001 --name filesystem --sync mcp_live_XXXX...

# Disable TUI, keep plain console output (useful in CI)
npx mcp-spy -t 3001 --no-tui

Standalone welcome & guided setup

Running npx mcp-spy without --target opens an interactive welcome screen instead of the proxy. You will see:

1. Subscription prompt — a summary of what Pro unlocks and the price. Press Y to open mcpspy.dev/pricing in your browser, or N to skip.
2. Guided setup wizard — a 4-step walkthrough that shows you how to connect the official @modelcontextprotocol/server-filesystem server to MCP-SPY and your MCP client. Navigate with → / N and go back with ← / P.

# Terminal 1 — start the MCP server on port 3001
npx -y @modelcontextprotocol/server-filesystem \
    --transport sse --port 3001 ~/Documents

# Terminal 2 — start MCP-SPY proxy (TUI opens automatically)
npx mcp-spy -t 3001 --name filesystem

# Claude Desktop config — point at the PROXY (4000), not the server (3001)
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "url": "http://localhost:4000"
    }
  }
}
# Use "url" — not "command"/"args" — otherwise Claude Desktop
# spawns the server directly and bypasses the proxy entirely.

Keyboard shortcuts

These shortcuts work once the TUI is running with an active proxy.

If you prefer plain terminal output without the TUI (useful in CI pipelines), add the --no-tui flag when starting MCP-Spy.

MCP-Spy works with any MCP server. You do not need to change your server code at all. If you are building a Node.js MCP server using the official @modelcontextprotocol/sdk:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-tool", version: "1.0.0" });

// Your tool definitions...

const transport = new StdioServerTransport();
await server.connect(transport);

Run your server: node server.js on port 3000. Then start MCP-Spy: npx mcp-spy --target 3000.

Using the official mcp Python package. MCP-Spy intercepts the stdio stream transparently.

import asyncio
from mcp.server.stdio import stdio_server
from mcp.server import Server

app = Server("my-tool")

@app.tool()
async def get_weather(location: str):
    """Returns current weather for a location."""
    return f"It is 72°F and sunny in {location}"

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            app.create_initialization_options()
        )

if __name__ == "__main__":
    asyncio.run(main())

Using the mark3labs/mcp-go package. Compile your server, run it on a port, and point MCP-Spy at it.

package main

import (
	"context"
	"fmt"
	"github.com/mark3labs/mcp-go/mcp"
	"github.com/mark3labs/mcp-go/server"
)

func main() {
	s := server.NewMCPServer("my-tool", "1.0.0",
		server.WithToolCapabilities(true),
	)

	tool := mcp.NewTool("get_weather",
		mcp.WithDescription("Get weather for a location"),
		mcp.WithString("location", mcp.Required()),
	)

	s.AddTool(tool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
		loc := req.Params.Arguments["location"].(string)
		return mcp.NewToolResultText(fmt.Sprintf("Sunny in %s", loc)), nil
	})

	if err := server.ServeStdio(s); err != nil {
		panic(err)
	}
}

Using the mcp-rs crate. Compile your binary and point MCP-Spy at the running process.

use mcp_rs::server::Server;
use mcp_rs::transport::stdio::StdioTransport;
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let transport = StdioTransport::new();
    let mut server = Server::new(transport);

    // Add tools here...

    server.listen().await?;
    Ok(())
}

Running multiple MCP servers simultaneously

Use --name to label each instance. Run each in a separate terminal:

# Terminal 1 — filesystem MCP
npx mcp-spy --target 3000 --name filesystem --sync YOUR_KEY

# Terminal 2 — GitHub MCP
npx mcp-spy --target 3001 --name github --sync YOUR_KEY

In the dashboard, each log shows its server label. Click a label to filter the list to that server only.

Where your data is stored

npx mcp-spy --target 3000 --sync mcp_live_your_api_key_here