MCP Debug

A debugging and development tool that helps test, record, and replay MCP server interactions via a proxy.

other

0

GitHub Stars

other

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "standardbeagle-mcp-debug": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/filesystem",
        "/home/user"
      ],
      "env": {
        "MCP_DEBUG": "1",
        "MCP_LOG_FILE": "/tmp/mcp-debug.log",
        "MCP_CONFIG_PATH": "./config.yaml",
        "MCP_RECORD_FILE": "session.jsonl"
      }
    }
  }
}

You can develop, test, and debug MCP servers efficiently with MCP Debug. This toolset lets you hot-swap server implementations, record and replay sessions, and manage multiple servers through a single proxy, making it easier to iterate on MCP-based systems with confidence.

How to use

You will run MCP Debug in proxy mode to route traffic to your MCP servers. Start by configuring a proxy that points to your local or remote MCP servers, then use the built-in tools to add, remove, or swap servers without interrupting connected clients. You can also record traffic for later playback to validate behavior or generate documentation.

How to install

Prerequisites: you need a supported runtime depending on how you install MCP Debug. You can use uvx (Python) or npx (Node.js) for quick starts, or install via the language-specific package managers if you prefer a direct approach.

# Using uvx (Python - recommended)
uvx mcp-debug --help

# Using npx (Node.js)
npx @standardbeagle/mcp-debug --help

# Or install globally
pip install mcp-debug              # Python
npm install -g @standardbeagle/mcp-debug  # Node.js

# Or build from source
go install github.com/standardbeagle/mcp-debug@latest

Additional setup notes

You can start a proxy with a configuration file to route traffic to a set of MCP servers. The example below demonstrates a typical setup where a filesystem MCP server is configured via a command that uses npx to launch the server package with its arguments.

# config.yaml
servers:
  - name: "filesystem"
    prefix: "fs"
    transport: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/filesystem", "/home/user"]
    timeout: "30s"

proxy:
  healthCheckInterval: "30s"
  connectionTimeout: "10s"
  maxRetries: 3

Security and best practices

Keep your proxy configuration up to date and limit access to the management API to trusted environments. When hot-swapping servers, ensure you have proper rollback plans and keep recordings and playback sessions secure, especially if they contain sensitive data.

Troubleshooting tips

If a server appears disconnected after a swap, use the management commands to disconnect and reconnect with the new command, then verify that clients re-establish connections smoothly.

Available tools

Hot Swap Development

Replace server implementations or update binaries without disconnecting MCP clients, while preserving the tool interface and enabling a graceful disconnect/reconnect workflow.

Session Recording

Capture JSON-RPC traffic to create documentation, reproduce issues, and support regression testing.

Playback Testing

Replay recorded client or server traffic to validate server behavior or to test client implementations against known responses.

Development Proxy

Aggregate multiple MCP servers under a single proxy with real-time connection monitoring, lifecycle control, and comprehensive logging.