Debugging MCP

Unit Testing Tools

import pytest
from mcp.testing import MCPTestClient

@pytest.fixture
def client():
    server = create_test_server()
    return MCPTestClient(server)

def test_search_tool(client):
    result = client.call_tool("search", query="test")
    assert "results" in result
    assert len(result["results"]) > 0

Mock Servers

Test client code without real server:

from mcp.testing import MockMCPServer

mock_server = MockMCPServer()
mock_server.register_response(
    tool="search",
    response={"results": ["item1", "item2"]}
)

client = MCPClient(mock_server)
result = client.call_tool("search")
# Returns mocked response

Protocol Inspection

View raw MCP messages:

client = MCPClient(server, debug=True)

# Logs all JSON-RPC messages:
# → {"method": "call_tool", "params": {...}}
# ← {"result": {...}}

Error Reproduction

Capture and replay issues:

import mcp.recording

# Record session
with mcp.recording.record("debug.mcplog"):
    client.call_tool("search", query="problematic")

# Later: Replay to debug
with mcp.recording.replay("debug.mcplog"):
    # Exact same execution without live server
    client.call_tool("search", query="problematic")

Logging

Detailed logging helps debugging:

import logging

logging.basicConfig(level=logging.DEBUG)

# Shows:
# Tool call: search(query=...)
# Tool latency: 234ms
# Tool result: {...}
# Tool error: ...

Common Issues

Timeout

Problem: Tool takes >30 seconds
Fix: Increase timeout or optimize tool

Connection Error

Problem: Client can't reach server
Fix: Check server running, firewall, network

Missing Tool

Problem: Tool not found on server
Fix: Rediscover tools or restart server

Invalid Input

Problem: Client sends wrong parameter types
Fix: Check tool schema, validate before sending