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
uvx mcp-debug --help
npx @standardbeagle/mcp-debug --help
pip install mcp-debug
npm install -g @standardbeagle/mcp-debug
go install github.com/standardbeagle/mcp-debug@latest
Quick Start
uvx mcp-debug --proxy --config config.yaml
mcp-tui uvx mcp-debug --proxy --config config.yaml
Usage
Proxy Mode
uvx mcp-debug --proxy --config config.yaml
uvx mcp-debug --proxy --config config.yaml --record session.jsonl
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
uvx mcp-debug --playback-client session.jsonl | ./your-mcp-server
mcp-tui uvx mcp-debug --playback-server session.jsonl
Configuration
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"
MCP_DEBUG=1
MCP_RECORD_FILE="session.jsonl"
MCP_CONFIG_PATH="./config.yaml"
Development Workflow
mcp-tui uvx mcp-debug --proxy --config empty-config.yaml
server_add: {name: myserver, command: ./my-server-v1}
go build -o my-server-v2
server_disconnect: {name: myserver}
server_reconnect: {name: myserver, command: ./my-server-v2}
CLI Commands
uvx mcp-debug --help
uvx mcp-debug --version
uvx mcp-debug config init
uvx mcp-debug config show
uvx mcp-debug config validate
uvx mcp-debug env list
uvx mcp-debug env check
uvx mcp-debug tools list
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
go build -o mcp-debug .
go build -ldflags "-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse HEAD)" -o mcp-debug .
go test ./...
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE for details.