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/sse

Free. No signup required. Runs entirely on your machine.

The problem it solves

MCP servers fail silently. Your coding agent stops calling tools but gives no useful error. Is the server down? Is SSE broken? Are events malformed? Did tools/list time out? badgr-mcp-doctor runs the full diagnostic sequence and tells you exactly what's wrong.

Quick start

# Diagnose an MCP server
npx badgr-mcp-doctor --url http://localhost:3000/sse

# Machine-readable JSON (for CI or scripts)
npx badgr-mcp-doctor --url http://localhost:3000/sse --json

# Dry-run a specific tool
npx badgr-mcp-doctor --url http://localhost:3000/sse --tool my_tool_name

# Longer timeout for slow servers
npx badgr-mcp-doctor --url http://localhost:3000/sse --timeout-ms 20000

# Show optional hosted monitoring link
npx badgr-mcp-doctor connect

CLI flags

| Flag | Description | |------|-------------| | --url <url> | MCP server SSE endpoint, e.g. http://localhost:3000/sse | | --timeout-ms <n> | Connection timeout in milliseconds (default: 10000) | | --tool <name> | Optional: dry-run a specific tool by name | | --json | Output machine-readable JSON |

Commands:

| Command | Description | |---------|-------------| | connect | Show the optional AI Badgr hosted MCP monitoring link |

Exit codes: 0 = all checks passed or warnings only, 1 = one or more failures, 2 = bad usage

What it checks

Each diagnostic runs in sequence and stops early if a hard failure is found:

| Step | Check | |------|-------| | 1 | HTTP connection — server responds to the SSE endpoint | | 2 | SSE event parsing — events arrive and are valid JSON | | 3 | tools/list — JSON-RPC call returns a list of tool objects | | 4 | Dry-run tool call — invokes the first tool (or --tool) with {dryRun: true} |

Example output

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

  ✓  HTTP connection: 200 OK
  ✓  SSE events: valid JSON payloads received
  ✗  tools/list: timeout after 10000ms

  The server connected but tools/list never responded.
  Common causes: server still initializing, blocking startup code, wrong endpoint path.

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

TypeScript API

import { runMcpDoctor } from "badgr-mcp-doctor";

const result = await runMcpDoctor({
  url: "http://localhost:3000/sse",
  timeoutMs: 15_000,
  toolName: "my_tool",  // optional: dry-run a specific tool
});

for (const check of result.checks) {
  console.log(check.status, check.label, check.detail);
}

Types:

interface McpDoctorOptions {
  url: string;
  timeoutMs?: number;   // default: 10000
  toolName?: string;
}

interface McpDoctorResult {
  checks: DiagnosticCheck[];
  report: JsonReport;
}

Requirements

• Node.js 18+
• An MCP server running and accessible at the given URL