17. Debugging MCP Servers

Chapter 17 of 22 · 20 min

KEY INSIGHT

Debugging MCP servers requires understanding both the protocol's message flow and the server's runtime behaviorΓÇöinspecting at multiple levels reveals different failure modes. Start with protocol-level debugging. MCP communicates via JSON-RPC, so log all incoming and outgoing messages: ```python import logging import json class ProtocolLogger: def __init__(self, logger: logging.Logger): self.logger = logger def log_request(self, method: str, params: dict): self.logger.debug(f"ΓåÆ {method}: {json.dumps(params)}") def log_response(self, id: int, result: any): self.logger.debug(f"ΓåÉ Response {id}: {json.dumps(result)}") def log_error(self, id: int, error: dict): self.logger.error(f"Γ£ù Error {id}: {error}") logger = ProtocolLogger(logging.getLogger("mcp.protocol")) ``` For connection-level issues, verify the transport is properly established. Check that the server responds to the initial handshake: ```bash # Test server health curl -X POST http://localhost:8000/health \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 0}' # Monitor active connections ss -tlnp | grep 8000 lsof -i :8000 ``` Python debugging with `pdb` or `breakpoint()` works within async contexts, but consider using `aiopdb` or structured logging for production debugging: ```python @mcp.tool() async def complex_operation(data: str) -> str: # Add conditional breakpoints for specific inputs if "DEBUG_TRIGGER" in data: breakpoint() # Only pauses on specific data # Log intermediate states logger.info(f"Processing {data[:50]}...") result = await process_data(data) logger.info(f"Completed, result length: {len(result)}") return result ``` Memory and performance profiling identify bottlenecks: ```python import tracemalloc import time @mcp.tool() def profiled_operation(data: list): tracemalloc.start() start = time.perf_counter() result = heavy_computation(data) current, peak = tracemalloc.get_traced_memory() elapsed = time.perf_counter() - start tracemalloc.stop() return { "result": result, "memory_mb": peak / 1024 / 1024, "elapsed_seconds": elapsed, } ``` For integration issues, mock the AI client to replay scenarios: ```python class MockMCPClient: """Replay recorded MCP sessions for debugging.""" def __init__(self, trace_file: str): with open(trace_file) as f: self.session = json.load(f) async def replay(self, server): for request in self.session["requests"]: response = await server.handle(request) expected = request.get("expected_response") if expected and response != expected: print(f"MISMATCH at {request['id']}:") print(f" Expected: {expected}") print(f" Got: {response}") ```

EXERCISE

Enable verbose logging in an existing MCP server. Trigger several tool calls and examine the logged protocol messages. Identify where delays occur and trace them to specific code paths.