mcp-debug

mcp-debug is a Go-based command-line tool designed for debugging MCP (Model Context Protocol) servers. It lets you connect to any MCP server over the streamable-http transport, inspect available capabilities, and debug tool integrations. The tool also supports an interactive REPL for exploring resources, prompts, and commands, and can operate as an MCP server itself to integrate with AI assistants or automation workflows. When running, you’ll get verbose logging of JSON-RPC messages to help diagnose transport or protocol issues, and you can enable self-update and shell autocompletion for Bash, Zsh, Fish, and PowerShell.

To connect to a protected MCP server, you can leverage OAuth 2.1 authentication with automatic discovery, token audience binding, and PKCE validation. The CLI can discover the authorization server, retrieve a CIMD (Client ID Metadata Document), and fall back to Dynamic Client Registration if CIMD is not supported, then open a browser to complete authorization and obtain an audience-bound token for subsequent requests.

Prerequisites:

• Go toolchain installed (go version 1.20+ recommended)
• Internet access to fetch modules

Install the mcp-debug tool (latest):

# Install the latest stable release into your Go bin directory
go install github.com/giantswarm/mcp-debug@latest

# Ensure your Go bin directory is in PATH (commonly $HOME/go/bin)
export PATH=$PATH:$(go env GOPATH)/bin

Build from source (alternative):

# Clone the repository
git clone https://github.com/giantswarm/mcp-debug.git
cd mcp-debug

# Build the binary
go build -o mcp-debug ./...

# Move or symlink the binary into your PATH as desired
mv mcp-debug /usr/local/bin/

Verify installation:

mcp-debug --version

If you prefer a specific version, replace latest with a version tag or commit hash in the install command.

Tips and common scenarios:

• OAuth 2.1 support is included by default for protected MCP servers. Ensure CIMD (Client ID Metadata Document) is accessible or allow Dynamic Client Registration as a fallback.
• Use --repl to enter the interactive shell and explore available tools, resources, and prompts.
• Use --mcp-server to run mcp-debug as an MCP server for AI assistant integrations.
• Enable verbose logging for deeper insights into JSON-RPC messages and transport behavior with appropriate flags (see usage guide).
• Autocompletion scripts can be generated and installed for Bash, Zsh, Fish, and PowerShell to speed up commands.
• If you run into OAuth browser prompts, ensure a reachable redirect URI and that your environment supports opening a browser from the CLI.