debug MCP server
Commit Nov 14, 2026Inspect MCP server capabilities, debug tool integrations, and test server notifications using an interactive REPL and verbose JSON-RPC logging.
Also known as giantswarm/mcp-debug
- Stars
- 38
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is debug MCP?
debug inspects MCP server capabilities, debug tool integrations, and test server notifications using an interactive REPL and verbose JSON-RPC logging.
Summary generated from the project's README
About debug MCP server
Debugging MCP server capabilities and tool integrations is the primary function of this command-line tool. Developers use it to inspect resources, test server notifications, and examine JSON-RPC messages through verbose logging. It works with any server utilizing the streamable-http transport and can function as an MCP server itself to integrate with AI assistants like Cursor.
Security is handled through full OAuth 2.1 compliance, supporting automatic discovery, PKCE validation, and resource indicators. Users can connect to protected endpoints using the --oauth flag, which manages authorization via a browser and supports both Client ID Metadata Documents and Dynamic Client Registration. The tool provides an interactive REPL for exploring prompts and tools, alongside shell autocompletion for Bash, Zsh, Fish, and PowerShell.
What you can do with it
- 1Inspect server capabilities interactivelyUse the interactive REPL to explore available tools, resources, and prompts on a connected server.
- 2Debug JSON-RPC communicationsExamine detailed JSON-RPC message logs to troubleshoot communication issues between the client and server.
- 3Test OAuth 2.1 authentication flowsVerify secure connections to protected servers using automatic discovery and PKCE validation.
- 4Integrate with AI assistantsRun the tool in MCP server mode to allow AI assistants like Cursor to connect to it.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegiantswarm/mcp-debug is public and reachablegithub.com/giantswarm/mcp-debug ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/giantswarm/mcp-debug ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 5.9 / 10; weakest: Code-Review 0, Token-Permissions 0, CII-Best-Practices 0scorecard.dev/viewer/?uri=github.com/giantswarm/mcp-debug ↗Partial 9/15
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP Debug
mcp-debug is a command-line tool for debugging MCP (Model Context Protocol) servers. It helps developers inspect MCP server capabilities, debug tool integrations, and test server notifications.
Key Features
- Connect to any MCP Server: Works with servers using
streamable-httptransport. - OAuth 2.1 Authentication: Full MCP authorization specification (2025-11-25) compliance with security-first defaults
- Automatic discovery (RFC 9728 Protected Resource Metadata, RFC 8414 AS Metadata)
- Resource Indicators (RFC 8707) for token audience binding
- PKCE validation (required by MCP spec)
- Dynamic Client Registration (RFC 7591) and Client ID Metadata Documents
- Step-up authorization for runtime permission escalation
- Intelligent scope selection (auto and manual modes)
- Interactive REPL: Explore available tools, resources, and prompts interactively.
- MCP Server Mode: Acts as an MCP server itself, allowing integration with AI assistants like Cursor.
- Verbose Logging: Detailed logging of JSON-RPC messages for in-depth debugging.
- Self-Update: Keep the tool up-to-date with a single command.
- Shell Autocompletion: Generates autocompletion scripts for Bash, Zsh, Fish, and PowerShell.
Getting Started
Installation
To build the tool from source and install it in your PATH:
go install github.com/giantswarm/mcp-debug@latest
Documentation
For detailed instructions on all features:
- ➡️ mcp-debug Usage Guide - Complete feature guide
- ➡️ OAuth 2.1 Documentation - Comprehensive OAuth authentication guide
OAuth 2.1 Quick Start
Connect to a protected MCP server with automatic discovery:
./mcp-debug --oauth --endpoint https://mcp.example.com/mcp
This automatically:
- Discovers the authorization server (RFC 9728)
- Validates PKCE support (required by MCP spec)
- Uses the official Client ID Metadata Document (CIMD)
- Falls back to Dynamic Client Registration if CIMD is not supported
- Opens your browser for authorization
- Connects with audience-bound tokens (RFC 8707)
Client ID Metadata Document (CIMD)
mcp-debug uses CIMD by default for OAuth authentication. The official client metadata is hosted at:
https://giantswarm.github.io/mcp-debug/client.json
This allows OAuth-protected MCP servers to identify mcp-debug without requiring pre-registration. The authorization server fetches the metadata from this URL and displays "MCP Debugger CLI" on the consent screen.
If you need to use a custom CIMD or disable it:
# Use a custom CIMD URL
./mcp-debug --oauth --oauth-client-id-metadata-url https://example.com/my-client.json --endpoint https://mcp.example.com/mcp
# Disable CIMD and force Dynamic Client Registration
./mcp-debug --oauth --oauth-disable-cimd --endpoint https://mcp.example.com/mcp
See the OAuth Documentation for detailed guides, examples, and troubleshooting.
Basic Examples
Connect to a server and listen for notifications:
./mcp-debug --endpoint http://localhost:8090/mcp
Start the interactive REPL:
./mcp-debug --repl
Run as an MCP server for AI assistant integration:
./mcp-debug --mcp-server
Refer to the usage guide for more advanced examples.
Contributing
Contributions are welcome! Please open an issue or submit a pull request.
License
mcp-debug is licensed under the Apache 2.0 License.
debug MCP questions
How do I connect to an MCP server using OAuth?
You can connect to a protected MCP server with automatic discovery by using the --oauth flag and specifying the endpoint.