Debug an MCP Server Systematically

When “MCP is broken,” isolate the failing layer instead of changing random protocol code.

1. Transport

Can the client start the stdio process or reach the HTTP URL? For stdio, make sure debug output goes to stderr rather than stdout.

2. Protocol/discovery

Can the client discover server capabilities and protocol version? Check SDK compatibility before assuming your tool implementation is wrong.

3. Schema

Inspect the tool schema. Required fields, enums, unions, or output schemas may differ from what you intended.

4. Authorization

Separate missing/invalid credentials from valid identity with insufficient permission.

5. Business logic

Invoke the underlying service independently of MCP. If it fails there, the protocol adapter is not the root cause.

6. Downstream dependency

Capture HTTP status, database timeout, queue state, or rate-limit metadata without exposing secrets to the model.