Official debugging and testing tool for MCP servers. Inspect server capabilities, test tool calls, validate responses, and debug protocol communication in real-time.
## MCP Inspector: The Essential Debugging Tool for MCP Development The **MCP Inspector** is the official debugging and testing tool for Model Context Protocol servers. Whether you're building a new MCP server or troubleshooting an existing integration, MCP Inspector provides the visibility and control you need to ensure your servers work correctly with Google Antigravity and other MCP clients. ### Why MCP Inspector? Building and integrating MCP servers can be challenging without proper tooling. Common issues include: - Protocol mismatches between client and server - Incorrect tool definitions or parameter schemas - Malformed responses that cause client errors - Silent failures without clear error messages MCP Inspector solves these problems by providing a dedicated environment for testing and validating your MCP servers before deploying them in production. ### Key Features #### 1. Server Connection Testing Connect to any MCP server and verify it responds correctly: - **Transport Validation**: Test stdio, SSE, and WebSocket transports - **Handshake Verification**: Ensure proper protocol initialization - **Capability Discovery**: See what features the server advertises - **Version Compatibility**: Check protocol version compatibility #### 2. Tool Discovery and Documentation Explore available tools with full documentation: - List all tools exposed by the server - View parameter schemas with type information - See example inputs and expected outputs - Understand tool descriptions and usage #### 3. Interactive Tool Testing Test tool calls in real-time: ``` > list_tools Available tools: - read_file(path: string) - Read contents of a file - write_file(path: string, content: string) - Write content to a file - search(query: string, limit?: number) - Search files > call read_file {"path": "/tmp/test.txt"} Result: { "content": "Hello, World!", "size": 13, "modified": "2024-01-15T10:30:00Z" } ``` #### 4. Response Validation Ensure server responses conform to the MCP specification: - **Schema Validation**: Verify responses match expected types - **Error Handling**: Test error responses and edge cases - **Content Formatting**: Check text and image content blocks - **Metadata Validation**: Verify all required fields are present #### 5. Protocol Message Inspection Debug at the protocol level: - View raw JSON-RPC messages - Inspect request/response pairs - Monitor notification events - Trace full communication flow ### Installation and Setup MCP Inspector runs as a standalone tool: ```bash # Install globally npm install -g @modelcontextprotocol/inspector # Or run with npx npx @modelcontextprotocol/inspector ``` ### Usage Modes #### Interactive Mode Launch the inspector with a web UI for visual exploration: ```bash mcp-inspector --ui ``` This opens a browser-based interface where you can: - Connect to servers graphically - Browse tools with auto-complete - View formatted responses - Save test sessions for later #### CLI Mode Test servers from the command line: ```bash # Connect to a server mcp-inspector connect "npx -y @anthropic/mcp-server-filesystem" --args "/tmp" # List tools mcp-inspector list-tools # Call a specific tool mcp-inspector call read_file --param path=/tmp/file.txt ``` #### CI/CD Integration Run automated tests in your pipeline: ```bash # Validate server starts correctly mcp-inspector validate ./my-mcp-server # Run test suite mcp-inspector test ./my-mcp-server --tests ./tests/mcp-tests.json ``` ### Debugging Common Issues #### Server Won't Connect - Check the command and arguments are correct - Verify required environment variables are set - Ensure the server process starts without errors #### Tools Not Appearing - Verify `list_tools` handler is implemented - Check tool definitions have valid schemas - Ensure tools are registered during initialization #### Tool Calls Failing - Validate input parameters match the schema - Check for required parameters - Verify the tool handler returns proper responses #### Slow Responses - Use the timing panel to identify bottlenecks - Check for blocking I/O in tool handlers - Verify external API calls are responsive ### Best Practices for MCP Development 1. **Test Early and Often**: Run Inspector during development, not just at the end 2. **Validate Schemas**: Ensure your tool schemas are complete and accurate 3. **Handle Errors Gracefully**: Test error cases and edge conditions 4. **Document Tools**: Write clear descriptions for each tool 5. **Version Your Server**: Include version info for debugging ### Integration with Development Workflow MCP Inspector fits seamlessly into your development process: - **During Development**: Rapid iteration with instant feedback - **Before Commits**: Validate changes don't break existing functionality - **In CI/CD**: Automated testing ensures quality - **For Debugging**: Quickly isolate issues in production ### Advanced Features #### Custom Test Suites Create reusable test suites: ```json { "tests": [ { "name": "Read file returns content", "tool": "read_file", "params": {"path": "/tmp/test.txt"}, "expect": {"content": "Hello"} } ] } ``` #### Performance Profiling Measure tool execution times: - Request latency tracking - Memory usage monitoring - Concurrent call testing #### Protocol Replay Record and replay sessions: - Capture production issues - Reproduce bugs locally - Share test cases with team members ### Getting Started 1. Install MCP Inspector globally or use npx 2. Start your MCP server 3. Connect the Inspector to your server 4. Explore tools and test functionality 5. Validate responses before production deployment MCP Inspector is an essential tool for anyone building or integrating MCP servers, providing the visibility needed to create reliable, production-ready integrations.
{
"mcpServers": {
"mcp-inspector": {
"args": [
"-y",
"@modelcontextprotocol/inspector"
],
"command": "npx"
}
}
}