mcp-debugging-specialist

What problem does it solve?

This Skill provides a structured, step-by-step approach to diagnose and resolve MCP server connection issues, tool invocation failures, protocol errors, server crashes, and timeouts so integrations reliably expose AI tools.

Core Features & Use Cases

• Configuration validation: Check MCP server entries, command/args, environment variables, and JSON syntax to catch setup mistakes.
• Independent server testing: Run the server command manually, inspect startup errors, and verify basic endpoints before integrating with the client.
• Log-driven diagnosis: Tail and search Claude and MCP logs for connection attempts, timeouts, crashes, and protocol errors to pinpoint failures.
• Tool discovery and invocation checks: Confirm registered tool names, test simple tool calls, and inspect registration schemas to resolve "method not found" and timeout issues.
• Protocol and performance debugging: Compare protocol versions, validate JSON-RPC messages, enable verbose logging, and profile startup and call latency.
• Use case: When MCP tools fail to appear in the client, follow the checklist to determine whether the problem is configuration, server startup, registration, or protocol mismatch.

Quick Start

Open your Claude Code MCP config, run the configured server command manually to confirm it starts, tail the Claude MCP logs to observe connection attempts, and invoke a basic mcp__server__ping to verify the tool responds.