MCP Debug

Debug and develop MCP servers with hot-swapping, session recording, and playback testing

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-debug": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-debug"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

yaml

# 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

bash

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

bash

# 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

bash

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

Code

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

bash

# 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.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about MCP Debug

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mcp-debug": { "command": "npx", "args": ["-y", "mcp-debug"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mcp-debug?style=directory)](https://allmcps.com/mcp/mcp-debug)

HTML Embed

<a href="https://allmcps.com/mcp/mcp-debug"><img src="https://allmcps.com/api/badge/mcp-debug?style=directory" alt="MCP Debug on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to MCP Debug →Install in Claude Desktop Install in Cursor Install in VS Code

MCP Debug

Debug and develop MCP servers with hot-swapping, session recording, and playback testing

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-debug": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-debug"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

yaml

# 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

bash

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

bash

# 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

bash

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

Code

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

bash

# 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.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about MCP Debug

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mcp-debug": { "command": "npx", "args": ["-y", "mcp-debug"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mcp-debug?style=directory)](https://allmcps.com/mcp/mcp-debug)

HTML Embed

<a href="https://allmcps.com/mcp/mcp-debug"><img src="https://allmcps.com/api/badge/mcp-debug?style=directory" alt="MCP Debug on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to MCP Debug →Install in Claude Desktop Install in Cursor Install in VS Code