Debugging MCP connections

When a server does not work, the cause is usually mundane: a bad config, a failed handshake, or an unhandled error. A short checklist finds it quickly.

Isolate server from client #

Connect to the server directly with the MCP Inspector. If it works there but not in your client, the fault is the client config (command, path, env). If it fails in the Inspector too, the fault is the server.

Check the lifecycle #

A connection that never lists tools usually failed at initialize. Confirm the server actually starts (run its command in a terminal), that it speaks the transport the client expects (stdio vs HTTP), and that capability negotiation completed.

Read the logs and errors #

• For local servers, anything the server writes to stderr is your log; run the command by hand to see it.
• Check the host application's own MCP logs for connection errors.
• If tools appear but calls fail, the problem is inside the tool: log its inputs and exceptions.

When a tool only misbehaves against the real service (a rate limit, a rejected write, a webhook arriving out of order), you want to make that condition happen on demand rather than wait for it to recur. A test double like Mountebank can force a specific error or delay for a single service, which is often all you need to reproduce a one-service bug. When the failure only appears because two services disagree, or because state built up across several calls, a stateful replica reproduces it more faithfully. Arga Labs is one option there, since it holds the accumulated state and can replay the exact sequence, so you can trigger the failure as many times as it takes to fix the tool rather than waiting for production to hand it back to you.