Open Source•Apache-2.0 License

badgr-mcp-doctor

Diagnose MCP server problems — SSE connectivity, malformed events, tools/list failures, timeouts — in one command.

npx badgr-mcp-doctor --url http://localhost:3000/sseGitHub →

How it works

MCP servers fail silently — your coding agent just stops calling tools with no useful error. badgr-mcp-doctor runs a fixed diagnostic sequence against the server's SSE endpoint and stops early at the first hard failure.

1

Connect and parse events

Confirms the SSE endpoint responds over HTTP, then checks that events arrive and are valid JSON payloads.

2

Call tools/list

Sends the JSON-RPC tools/list call and confirms it returns a list of tool objects within --timeout-ms (default 10000ms).

3

Dry-run a tool

Invokes the first tool (or the one named with --tool) with { dryRun: true } to confirm it responds without error.

1

Install

Terminal
npx badgr-mcp-doctor --url http://localhost:3000/sse

Requires Node.js 18+ and an MCP server running and accessible at the given URL.

2

Usage

Point it at your MCP server's SSE endpoint. Add --tool to dry-run a specific tool, or --json for CI-friendly output.

Terminal
npx badgr-mcp-doctor --url http://localhost:3000/sse
npx badgr-mcp-doctor --url http://localhost:3000/sse --tool my_tool_name --json

Example output

Terminal output
badgr-mcp-doctor — http://localhost:3000/sse

  ✓  HTTP connection: 200 OK
  ✓  SSE events: valid JSON payloads received
  ✓  tools/list: 4 tools found (search, read_file, write_file, run_command)
  ✓  Dry-run tool call: search responded without error

Commands

badgr-mcp-doctor --url <url>Run the full diagnostic sequence against an MCP server's SSE endpoint.
badgr-mcp-doctor connectShow the optional AI Badgr hosted MCP monitoring link.

What's included

✓Diagnoses SSE connectivity, malformed events, and timeouts
✓Checks tools/list and reports how many tools were found
✓Dry-runs a specific tool with --tool <name>
✓Configurable connection timeout via --timeout-ms
✓Stops early and explains the first hard failure it finds
✓Machine-readable --json output for CI
✓Optional connect command for hosted MCP monitoring
View on GitHub →

Ready to try badgr-mcp-doctor?

npx badgr-mcp-doctor --url http://localhost:3000/sse — no account needed to get started.

Install from npmGet cloud API key