debug-mcp

The debug-mcp skill provides a structured, command-line-driven approach to troubleshooting Model Context Protocol (MCP) servers. Designed primarily for developers working with Microsoft Copilot Studio, this skill helps identify and resolve common communication issues where tool schemas are incorrectly interpreted or execution fails due to protocol mismatches. By leveraging static analysis through grep, manual JSON-RPC verification, and a proven checklist of constraints, it ensures that your MCP implementation remains stable, compliant, and optimized for AI agent consumption.

• Performs automated scans for problematic patterns like optional parameters, complex types (Union, Optional, List, Dict), and default values that interfere with Copilot Studio parsing.

• Includes a systematic verification protocol to test server connectivity, validate tool schema registration, and audit runtime responses.

• Implements best-practice guidelines for tool design, such as flattening complex objects and ensuring boolean parameters are explicitly handled as strings.

• Integrates directly with project-specific documentation and expert-tier troubleshooting agents like mcp-copilot-expert to apply known fixes.

• Use this skill when Copilot Studio fails to render tools correctly or defaults to showing raw JSON-RPC parameters.

• Ideal for developers who need to keep tool counts under the recommended 70-limit for optimal performance in agentic environments.

• Ensure all tool definitions are analyzed for potential mismatches between the Python implementation and the MCP specification.

• Practical tips include separating multi-parameter tools into distinct functions to avoid optional parameter limitations and maintaining clear, descriptive docstrings for better model interpretability.

• Works best when combined with standard server logging to isolate start-up errors and connectivity issues early in the development lifecycle.