arcade-mcp/libs/arcade-mcp-server/docs/clients/inspector.md

MCP Inspector

The MCP Inspector is a powerful debugging and testing tool for MCP servers. It provides a web-based interface to interact with your Arcade MCP server, test tools, and monitor protocol messages.

Installation

Install the MCP Inspector globally:

npm install -g @modelcontextprotocol/inspector

Or use npx to run without installing:

npx @modelcontextprotocol/inspector

Basic Usage

Connecting to HTTP Servers

For MCP servers running over HTTP:

# Start your MCP server
uv run server.py

# In another terminal, start the inspector
mcp-inspector http://localhost:8000/mcp

Connecting to stdio Servers

For stdio-based servers:

# Start the inspector with your server command
mcp-inspector "uv run server.py stdio"

# With additional project directory
mcp-inspector --cwd /path/to/project "uv run server.py stdio"

Inspector Features

Tool Explorer

The Tool Explorer shows all available tools with:

• Tool names and descriptions
• Parameter schemas
• Return type information
• Example invocations

Interactive Testing

Test tools directly from the interface:

1. Select a tool from the explorer
2. Fill in parameter values
3. Click "Execute" to run the tool
4. View results and execution time

Protocol Monitor

Monitor all MCP protocol messages:

• Request/response pairs
• Message timing
• Protocol errors
• Raw JSON data

Resource Browser

If your server provides resources:

• Browse available resources
• View resource contents
• Test resource operations

Prompt Templates

Test prompt templates if supported:

• View available prompts
• Fill template parameters
• Preview rendered prompts

Advanced Usage

Custom Environment

Pass environment variables to your server:

# Using env command
env ARCADE_API_KEY=your-key mcp-inspector "uv run server.py stdio"

# Using inspector's env option
mcp-inspector --env ARCADE_API_KEY=your-key "uv run server.py stdio"

Working Directory

Set the working directory for your server:

mcp-inspector --cwd /path/to/project "uv run server.py stdio"

Debug Mode

Enable verbose logging:

# Debug the inspector
mcp-inspector --debug "uv run server.py stdio"

# Server debug logging is configured in your server.py
# app = MCPApp(name="my_server", version="1.0.0", log_level="DEBUG")

Testing Workflows

Tool Development

1. Configure your server with hot reload:

   # In your server.py
   if __name__ == "__main__":
       transport = sys.argv[1] if len(sys.argv) > 1 else "http"
       app.run(transport=transport, host="127.0.0.1", port=8000, reload=True)
   

   Then run:

   uv run server.py
   

2. Connect the inspector:

   mcp-inspector http://localhost:8000/mcp
   

3. Develop and test:

   • Modify your tool code
   • Server auto-reloads
   • Test immediately in inspector

Performance Testing

Use the inspector to measure tool performance:

1. Enable timing in the Protocol Monitor
2. Execute tools multiple times
3. Analyze response times
4. Identify bottlenecks

Error Debugging

Debug tool errors effectively:

1. Enable debug mode on your server
2. Execute the failing tool
3. Check Protocol Monitor for error details
4. View server logs in terminal

Integration Testing

Test Suites

Create test suites using the inspector:

// test-tools.js
const tests = [
  {
    tool: "greet",
    params: { name: "World" },
    expected: "Hello, World!"
  },
  {
    tool: "calculate",
    params: { expression: "2 + 2" },
    expected: 4
  }
];

// Run tests via inspector API

Automated Testing

Combine with testing frameworks:

# test_mcp_tools.py
import subprocess
import json
import pytest

def test_tool_via_inspector():
    # Start server
    server = subprocess.Popen(
        ["python", "-m", "arcade_mcp_server"],
        stdout=subprocess.PIPE
    )

    # Use inspector's API to test tools
    # ...

Best Practices

Development Setup

1. Use Split Terminal:

   • Terminal 1: MCP server with reload
   • Terminal 2: Inspector
   • Terminal 3: Code editor

2. Enable All Debugging:

   # In server.py
   app = MCPApp(name="my_server", version="1.0.0", log_level="DEBUG")
   
   # Run with reload
   app.run(transport="http", host="127.0.0.1", port=8000, reload=True)
   

   Then run with environment file:

   uv run server.py
   

3. Save Test Cases:

   • Export successful tool calls
   • Build regression test suite
   • Document edge cases

Production Testing

1. Test Against Production Config:

   mcp-inspector "uv run server.py stdio"
   

2. Verify Security:

   • Test with limited permissions
   • Verify API key handling
   • Check error messages don't leak secrets

3. Load Testing:

   • Execute tools rapidly
   • Monitor memory usage
   • Check for resource leaks

Troubleshooting

Connection Issues

"Failed to connect"

1. Verify server is running
2. Check correct URL/command
3. Ensure ports aren't blocked
4. Try with --debug flag

"Protocol error"

1. Ensure server implements MCP correctly
2. Check for version compatibility
3. Review server logs
4. Verify transport type

Tool Issues

"Tool not found"

1. Verify tool is decorated with @tool
2. Check tool discovery in server
3. Ensure no import errors
4. Restart server and inspector

"Parameter validation failed"

1. Check parameter types match schema
2. Verify required parameters
3. Test with simpler values
4. Review tool documentation

Examples

Quick Test Session

# 1. Start a simple MCP server
cat > test_tools.py << 'EOF'
from arcade_mcp_server import tool
from typing import Annotated

@tool
def echo(message: Annotated[str, "Message to echo"]) -> str:
    """Echo the message back."""
    return message

@tool
def add(
    a: Annotated[int, "First number"],
    b: Annotated[int, "Second number"]
) -> Annotated[int, "Sum"]:
    """Add two numbers."""
    return a + b
EOF

# 2. Start inspector
mcp-inspector "uv run server.py stdio"

# 3. Test tools in the web interface

HTTP Server Testing

# 1. Create an MCPApp server
cat > app.py << 'EOF'
from arcade_mcp_server import MCPApp
from typing import Annotated

app = MCPApp(name="test-server", version="1.0.0")

@app.tool
def get_time() -> Annotated[str, "Current time"]:
    """Get the current time."""
    from datetime import datetime
    return datetime.now().isoformat()

if __name__ == "__main__":
    app.run(port=9000, reload=True)
EOF

# 2. Run the server
python app.py

# 3. Connect inspector
mcp-inspector http://localhost:9000/mcp

Debugging Session

# 1. Enable all debugging
export DEBUG=*
export MCP_DEBUG=true

# 2. Start server with verbose logging
# (configure log_level="DEBUG" in your server.py)
uv run server.py stdio 2>server.log

# 3. Start inspector with debugging
mcp-inspector --debug "uv run server.py stdio"