Skip to main content
MCP involves two processes talking over HTTP or stdio. Here’s how to debug them.

The tmux pattern

Run server and client in split terminals:
See both outputs side by side. Kill when done: tmux kill-session -t mcp

Structured logging

Log from inside tools:

Verbose mode

Or via environment:

Client-side log capture

Common issues

“Client does not advertise the sampling capability” Pass a sampling handler:
“Tool mutation attempted after server startup” Enable dynamic tools:
Connection refused Check the port: lsof -i :8000 Kill orphans: lsof -ti :8000 | xargs kill -9 Wrong URL The endpoint is http://127.0.0.1:8000/mcp, not just :8000.

When stuck

  1. Strip to minimal reproduction
  2. Check MCP spec compliance
  3. Test with MCP Inspector: pnpm dlx @anthropic/mcp-inspector
  4. Read server logs
Last modified on June 30, 2026