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
- Strip to minimal reproduction
- Check MCP spec compliance
- Test with MCP Inspector:
pnpm dlx @anthropic/mcp-inspector
- Read server logs
Last modified on June 30, 2026