Debugging the Bridge: Six MCP Fixes for Claude Desktop

Fix #1: Tool Names Must Match Zod Validation Pattern

The Problem: Our tool names included dots, like lap.health.ping. While dots are common in namespace conventions, the MCP specification enforces strict naming via Zod schema validation using the pattern ^[a-zA-Z0-9_-]{1,64}$.

The Symptom: Tools were silently rejected during the tools/list request. Claude Desktop received the tool list but validation failed before tools could be registered.

The Solution: Renamed all tools to use underscores: lap_health_ping, lap_core_status, etc.

// Before - FAILS validation
{
  "name": "lap.health.ping",
  "description": "..."
}

// After - PASSES validation  
{
  "name": "lap_health_ping",
  "description": "..."
}

Fix #2: Schema Properties Must Be Objects, Not Arrays

The Problem: Our initial implementation used "properties": [] for tools with no parameters. While Python's type system is forgiving, JSON Schema strictly requires properties to be an object type.

The Symptom: Schema validation failures in Claude Desktop, though the error was swallowed silently rather than surfaced to logs.

The Solution: Changed empty properties arrays to empty objects:

// Before - Invalid JSON Schema
{
  "inputSchema": {
    "type": "object",
    "properties": []  // ❌ Wrong type
  }
}

// After - Valid JSON Schema
{
  "inputSchema": {
    "type": "object", 
    "properties": {}  // ✅ Correct type
  }
}

Fix #3: MCP Requires Content Wrapper in Responses

The Problem: The MCP specification requires all tool responses to be wrapped in a specific structure: {"content": [{"type": "text", "text": "..."}]}. We were returning raw response data, assuming the framework would handle wrapping.

The Symptom: Tools would execute successfully on the server side, but Claude Desktop would treat responses as invalid and not display results.

The Solution: Added a wrapper function in the dispatcher:

def _wrap_mcp_content(result: Any) -> dict:
    """Wrap tool results in MCP content structure."""
    if isinstance(result, dict) and "content" in result:
        return result  # Already wrapped
    
    # Convert result to string and wrap
    text = json.dumps(result) if not isinstance(result, str) else result
    return {
        "content": [{
            "type": "text",
            "text": text
        }]
    }

Fix #4: Notification Handlers Must Return Empty String

The Problem: MCP uses JSON-RPC notifications (requests without IDs) for lifecycle events like notifications/initialized. Our dispatcher was treating these as errors when no handler was found, returning error responses for notification requests.

The Symptom: Connection would establish but immediately disconnect as Claude Desktop received error responses to its initialization notifications.

The Solution: Added explicit notification detection and empty string return:

async def dispatch(self, request: dict) -> str:
    """Dispatch MCP request to appropriate handler."""
    
    # Check if this is a notification (no "id" field)
    if "id" not in request:
        # Notifications don't expect responses
        return ""
    
    # Regular request-response handling...
    method = request.get("method")
    # ...

Fix #5: Stdio Transport Requires Pure JSON-RPC on Stdout

The Problem: The MCP stdio transport is extremely sensitive to stdout pollution. Any debug logs, print statements, or error messages to stdout break JSON-RPC parsing and cause silent connection failures.

The Symptom: Server would appear to start successfully, but Claude Desktop would disconnect immediately. Debugging was nearly impossible because we couldn't see what was happening.

The Solution: Redirected all stderr to a log file in the launch command:

// claude_desktop_config.json
{
  "mcpServers": {
    "lap-core": {
      "command": "wsl",
      "args": [
        "-e", "bash", "-c",
        "exec 2>/tmp/lap-mcp-stderr.log; source ~/.profile && cd ~/projects/lap_core && /home/kbroder/.local/bin/poetry run lap-mcp-stdio"
      ]
    }
  }
}

The exec 2>> syntax ensures stderr redirection happens before any Python code runs, catching even early import errors.

Fix #6: JSON-RPC Responses Must Keep id and jsonrpc

The Problem: Later deployments started using convenience helpers like Pydantic’s model_dump_json(exclude_none=True) or manual response.pop("id") cleanup. Those helpers remove "id" when it is null, violating the JSON-RPC 2.0 spec and causing Claude Desktop to reject otherwise valid responses.

The Symptom: Tool execution logs looked perfect, but the client silently dropped responses because required headers vanished when id was null.

The Solution: Never exclude "id" or "jsonrpc"; only gate result vs. error. Our Preflight Validator now checks for both exclude_none=True patterns and explicit .pop("id")/.pop("jsonrpc") calls.

# ✅ Keep id/jsonrpc even when None
payload = {
    "jsonrpc": "2.0",
    "id": request.id,
    "result": data,
}
return payload

# ❌ This removes id/jsonrpc
return payload.model_dump_json(exclude_none=True)