MCP Debug

MCP Debug

A debugging and development tool for Model Context Protocol (MCP) servers.

MCP Debug enables rapid development and testing of MCP servers with hot-swapping, session recording, and automated playback testing.

Features

Hot-Swap Development

• Replace server binaries without disconnecting MCP clients
• Add/remove servers dynamically during development
• Tool name preservation - same interface, new implementation
• Graceful disconnect/reconnect workflow for binary replacement

Session Recording & Playback

• Record JSON-RPC traffic for debugging and documentation
• Playback client mode - replay requests to test servers
• Playback server mode - replay responses to test clients
• Regression testing with recorded sessions

Development Proxy

• Multi-server aggregation with tool prefixing
• Real-time connection monitoring
• Management API for server lifecycle control
• Comprehensive logging

Installation

# 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

Quick Start

# Start proxy with a config file

uvx mcp-debug --proxy --config config.yaml

Or with mcp-tui for interactive testing

mcp-tui uvx mcp-debug --proxy --config config.yaml

Usage

Proxy Mode

# Basic proxy

uvx mcp-debug --proxy --config config.yaml

With recording

uvx mcp-debug --proxy --config config.yaml --record session.jsonl

With custom log file

uvx mcp-debug --proxy --config config.yaml --log /tmp/debug.log

Management Tools:

• server_add - Add a server: {name: "fs", command: "npx -y @mcp/filesystem /path"}
• server_remove - Remove server completely
• server_disconnect - Disconnect server (tools return errors)
• server_reconnect - Reconnect with new command
• server_list - Show all servers and status

Playback Modes

# Replay recorded requests to test a server

uvx mcp-debug --playback-client session.jsonl | ./your-mcp-server

Replay recorded responses to test a client

mcp-tui uvx mcp-debug --playback-server session.jsonl

Configuration

# 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

Environment Variables

MCP_LOG_FILE="/tmp/mcp-debug.log"  # Log location

MCP_DEBUG=1 # Enable debug logging MCP_RECORD_FILE="session.jsonl" # Auto-record sessions MCP_CONFIG_PATH="./config.yaml" # Default config

Development Workflow

# 1. Start with empty config

mcp-tui uvx mcp-debug --proxy --config empty-config.yaml

2. Add your server dynamically

server_add: {name: myserver, command: ./my-server-v1}

3. Test tools: myserver_read_file, myserver_process, etc.

4. Make changes and rebuild

go build -o my-server-v2

5. Hot-swap the server

server_disconnect: {name: myserver} server_reconnect: {name: myserver, command: ./my-server-v2}

6. Same tools work immediately with new implementation!

CLI Commands

uvx mcp-debug --help              # Show help

uvx mcp-debug --version # Show version uvx mcp-debug config init # Create default config uvx mcp-debug config show # Show current config uvx mcp-debug config validate # Validate config file uvx mcp-debug env list # List environment variables uvx mcp-debug env check # Check required env vars uvx mcp-debug tools list # List tools with details

Project Structure

mcp-debug/

├── main.go # CLI entry point ├── config/ # Configuration loading ├── client/ # MCP client implementation ├── integration/ # Proxy server and wrapper ├── discovery/ # Tool discovery ├── proxy/ # Request forwarding ├── playback/ # Recording and playback └── test-servers/ # Example MCP servers

Building

# Development build

go build -o mcp-debug .

Production build with version info

go build -ldflags "-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse HEAD)" -o mcp-debug .

Run tests

go test ./...

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.