Mcp Debug

io.github.standardbeaglePublished by GitHub account standardbeaglev1.1.6Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

A development proxy for MCP servers that supports hot-swapping server binaries, recording JSON-RPC sessions, and replaying them for testing.

What you can do
MCP Debug runs as a proxy in front of one or more MCP servers, aggregating their tools with prefixes and exposing management tools such as server_add, server_remove, server_disconnect, server_reconnect, and server_list. It can record JSON-RPC traffic to a session file and replay it in client or server mode for regression testing. It also provides CLI commands for config init/show/validate, environment checks, and tool listing.
When to use it
Use it while building or debugging your own MCP servers, when you want to swap a server binary without restarting the client, inspect or replay recorded sessions, or aggregate several servers behind one endpoint during development.
Requirements
Runs locally over stdio. Install via uvx (Python), npx (Node.js), pip, npm, or a Go build. A YAML config file is needed for proxy mode. Optional environment variables include MCP_LOG_FILE, MCP_DEBUG, MCP_RECORD_FILE, and MCP_CONFIG_PATH. No authentication is declared.
Before you install
The proxy starts and manages other server processes from commands given in its config, so only point it at commands you trust. Recording writes JSON-RPC traffic, which may include tool arguments and results, to a session file; treat those files as sensitive. Management tools can add, remove, disconnect, and reconnect servers.

Installation

In SourceWeft

  1. Open Mcp Debug in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

MCP Debug

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

[Go Version] [MCP Spec] [License: MIT] [PyPI] [npm]

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 globallypip install mcp-debug              # Pythonnpm install -g @standardbeagle/mcp-debug  # Node.js
# Or build from sourcego install github.com/standardbeagle/mcp-debug@latest

Quick Start

bash
# Start proxy with a config fileuvx mcp-debug --proxy --config config.yaml
# Or with mcp-tui for interactive testingmcp-tui uvx mcp-debug --proxy --config config.yaml

Usage

Proxy Mode

bash
# Basic proxyuvx mcp-debug --proxy --config config.yaml
# With recordinguvx mcp-debug --proxy --config config.yaml --record session.jsonl
# With custom log fileuvx 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 serveruvx mcp-debug --playback-client session.jsonl | ./your-mcp-server
# Replay recorded responses to test a clientmcp-tui uvx mcp-debug --playback-server session.jsonl

Configuration

yaml
# config.yamlservers:  - 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 locationMCP_DEBUG=1                         # Enable debug loggingMCP_RECORD_FILE="session.jsonl"     # Auto-record sessionsMCP_CONFIG_PATH="./config.yaml"     # Default config

Development Workflow

bash
# 1. Start with empty configmcp-tui uvx mcp-debug --proxy --config empty-config.yaml
# 2. Add your server dynamicallyserver_add: {name: myserver, command: ./my-server-v1}
# 3. Test tools: myserver_read_file, myserver_process, etc.
# 4. Make changes and rebuildgo build -o my-server-v2
# 5. Hot-swap the serverserver_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 helpuvx mcp-debug --version           # Show versionuvx mcp-debug config init         # Create default configuvx mcp-debug config show         # Show current configuvx mcp-debug config validate     # Validate config fileuvx mcp-debug env list            # List environment variablesuvx mcp-debug env check           # Check required env varsuvx 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

bash
# Development buildgo build -o mcp-debug .
# Production build with version infogo build -ldflags "-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse HEAD)" -o mcp-debug .
# Run testsgo test ./...

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Source: README.md at commit 28f7706

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.6LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts