MCP Debug CLI
A command-line debugger for MCP servers from Giant Swarm: a REPL for tools, OAuth 2.1 and an MCP server mode for Cursor
- 38 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The utility connects to the server you name and calls its tools, which may change data
- OAuth mode opens a sign-in to the server's account
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mcp-debugDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The utility connects to the server you name and calls its tools, which may change data
- OAuth mode opens a sign-in to the server's account
This is third-party code. Review the repository files before installing.
What it does
`mcp-debug` connects to an MCP server over the `streamable-http` transport and shows what it offers: tools, resources and prompts. The interactive `--repl` mode lets you call them by hand. Verbose logging of JSON-RPC messages is a separate switch, so you see exactly what went to the server and what came back. The utility listens for server notifications itself. Protected servers can be reached through OAuth 2.1 following the MCP specification of November 25, 2025. The utility discovers the authorization server, checks PKCE support, binds the token to the resource, and identifies itself with a CIMD client document or dynamic registration. Scopes are chosen automatically or by hand, with step-up when permissions are short. The `--mcp-server` flag turns the tool into an MCP server for Cursor and other clients. It also has self-update and completion scripts for Bash, Zsh, Fish and PowerShell.
Who it is for. MCP server authors and teams working out why an agent does not see a tool or fails authorization.
Good fit when
- A new MCP server is running and you want to see its tools and schemas before connecting an agent
- The agent does not call a tool and you check the raw JSON-RPC messages between client and server
- A server behind OAuth answers with a refusal and you want to walk through sign-in by hand and inspect discovery and scope choice
- You want to see which notifications the server sends to the client
Not a fit when
- The server runs over stdio only: the utility connects over `streamable-http`
- You want a web interface with call history: MCP Inspector covers that
- You need load testing or CI autotests: the REPL and logs are built for manual debugging
Example request
Connect to http://localhost:8090/mcp, list the server's tools and call the first one with test arguments.Limitations
Only the `streamable-http` transport is supported, and the utility does not open stdio servers.
Installation goes through `go install`, so Go is required. The README promises no prebuilt binaries.
In OAuth mode the browser opens on a consent page that shows the client name MCP Debugger CLI.
Details on OAuth and advanced scenarios live in `docs/usage.md` and `docs/oauth/`, not in the README itself.
How to disable. Delete the `mcp-debug` binary from `GOBIN` or `$GOPATH/bin`. If you used `--mcp-server`, remove the entry from the client config.
FAQ
How do I install mcp-debug?
Run `go install github.com/giantswarm/mcp-debug@latest`. The binary lands in Go's executables directory, so make sure it is on your `PATH`.
How do I connect to a server with OAuth?
Run `mcp-debug --oauth --endpoint <URL>`. The utility finds the authorization server, opens the browser for consent and connects with a resource-bound token.
What is CIMD?
A client metadata document at a URL that the authorization server fetches instead of requiring pre-registration. Set your own with `--oauth-client-id-metadata-url` and force dynamic registration with `--oauth-disable-cimd`.
Does the utility work with stdio servers?
No, the `streamable-http` transport is supported. A stdio server needs another debugger, such as MCP Inspector.
Can I connect mcp-debug to Cursor?
Yes: the `--mcp-server` flag runs the utility as an MCP server. The README gives no specific client config.
Discussion
No questions or reviews yet.
Related
CLI toolsA transparent proxy between an AI client and an MCP server: shows every JSON-RPC frame in the terminal, checks a capture in CI and exports spans
An MCP server that lets an agent read files, search code and run commands in a workspace
Command-line inspector for HTTP MCP servers: lists tools, schemas, prompts and resources and calls any tool by hand.
The openmcp CLI and a VS Code extension for debugging MCP servers: tools, prompts and resources, chat with a model, test cases
A terminal and browser client opens a chat between an Anthropic model and any MCP server so its tools can be tested.
A lightweight CLI to discover, inspect and call MCP server tools straight from the shell
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| MCP Debug (this card) | yes | 38 | |
| MCP Inspector | no | 11,243 | a web interface, CLI and terminal UI instead of a single REPL |
| mcp-cli | no | 1,282 | light tool calls from the command line without OAuth debugging |
README in short
The README lists features and gives an OAuth quick start with flag examples. Detailed guides sit in `docs/usage.md` and the `docs/oauth/` directory.