The Quick Answer

Launch MCP Inspector with npx to test your server interactively. No installation needed - just run directly:

$npx @modelcontextprotocol/inspector node build/index.js

The Inspector opens at http://localhost:6274 with a visual interface for testing tools, resources, and prompts. This enables real-time debugging without writing client code.

Prerequisites

• Node.js 18 or higher (22.7.5+ recommended for optimal performance)
• Built MCP server ready for testing
• Basic understanding of MCP server concepts

Installation

MCP Inspector requires no permanent installation. The tool runs directly through npx, which downloads and executes the latest version automatically. This approach ensures you always have the most recent features and bug fixes.

# For JavaScript/TypeScript servers
$npx @modelcontextprotocol/inspector node build/index.js
 
# For Python servers (requires mcp[cli] package)
$npx @modelcontextprotocol/inspector uvx mcp-server-example
 
# For servers from npm registry
$npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /path/to/directory

The Inspector spawns two processes: the web UI on port 6274 and a proxy server on port 6277. Both bind to localhost by default for security.

Configuration

Environment Variables

MCP Inspector supports several configuration options through environment variables. These control timeouts, ports, and connection behavior:

# Custom port configuration
$CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node server.js
 
# Timeout settings (milliseconds)
$MCP_SERVER_REQUEST_TIMEOUT=20000 npx @modelcontextprotocol/inspector node server.js
 
# Disable timeout reset on progress notifications
$MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false npx @modelcontextprotocol/inspector node server.js

The proxy server generates a session token on startup for security. Look for the authenticated URL in the console output - clicking this link opens the Inspector with automatic authentication.

Server Arguments and Environment

Pass arguments and environment variables to your server through the Inspector. This mimics how MCP clients like Claude Desktop would launch your server:

# Pass arguments to your server
$npx @modelcontextprotocol/inspector node server.js --port 8080 --debug
 
# Set server environment variables
$npx @modelcontextprotocol/inspector --env API_KEY=test123 --env DEBUG=true node server.js

Configuration files can store frequently used settings. Create an inspector-config.json file to avoid repetitive command-line arguments.

Usage

Connecting to Your Server

The Inspector interface provides intuitive controls for server connection. Upon launching, you'll see the connection panel on the left side:

1. Transport Selection: Choose stdio (recommended), SSE, or streamable-http
2. Command Entry: Specify how to launch your server
3. Environment Setup: Add any required environment variables
4. Connection: Click "Connect" to establish the link

Testing Tools

Navigate to the Tools tab to explore your server's capabilities. The Inspector displays all registered tools with their schemas and descriptions. Testing involves three steps:

// Example tool registration your server might have
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return { content: [{ type: "text", text: `Sum: ${a + b}` }] };
  }
});

In the Inspector, you can test this tool by entering parameter values in the UI form. The response appears immediately, showing both successful results and error messages. This rapid feedback loop accelerates development significantly.

Testing Resources

Resources represent data your server exposes to clients. The Resources tab lists all available resources with their URIs and MIME types. Click any resource to view its contents:

# Example resource in a Python MCP server
@server.list_resources()
async def handle_list_resources():
    return [
        Resource(
            uri="config://settings",
            name="Server Settings",
            description="Current server configuration",
            mimeType="application/json"
        )
    ]

The Inspector fetches and displays resource contents, helping verify data formatting and access permissions. Watch for resources that take too long to load or return unexpected data structures.

Testing Prompts

Prompts define reusable templates for AI interactions. The Prompts tab shows all registered prompts with their argument schemas. Test prompt generation by providing sample arguments:

// Prompt registration example
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name === "code_review") {
    const { language, code } = request.params.arguments;
    return {
      messages: [{
        role: "user",
        content: { type: "text", text: `Review this ${language} code:\n${code}` }
      }]
    };
  }
});

The Inspector renders the generated messages, allowing you to verify prompt construction before integration with AI clients.

Advanced Usage

Debugging with Request History

The History panel maintains a complete log of all interactions with your server. Each entry includes request parameters, response data, and timing information. This history persists throughout your session, enabling pattern analysis and regression testing.

Export history as JSON for documentation or automated testing. The exported data includes timestamps, making it valuable for performance analysis.

Using CLI Mode

CLI mode enables programmatic testing and CI/CD integration. Launch the Inspector in CLI mode for scriptable operations:

# List available tools
$npx @modelcontextprotocol/inspector --cli list-tools node server.js
 
# Call a specific tool
$npx @modelcontextprotocol/inspector --cli call-tool calculate_sum '{"a": 5, "b": 3}' node server.js
 
# Read a resource
$npx @modelcontextprotocol/inspector --cli read-resource "config://settings" node server.js

CLI mode outputs JSON by default, making it ideal for automated testing pipelines. Combine with jq or other JSON processors for advanced workflows.

Remote Server Testing

Test servers running on remote machines or in containers. The Inspector can connect to any MCP server accessible via HTTP:

# Connect to a remote SSE server
$npx @modelcontextprotocol/inspector --connect https://api.example.com/mcp/sse
 
# Connect with authentication
$npx @modelcontextprotocol/inspector --connect https://api.example.com/mcp/sse --bearer-token your-token-here

Remote testing helps verify deployment configurations and network-related issues before production release.

Common Issues

Connection Refused Errors

The Inspector frontend shows "Connection Error" with ERR_CONNECTION_REFUSED in the console. This typically indicates the proxy server isn't running or is blocked by security software. First, verify no other processes occupy the default ports:

# Check for port conflicts
$lsof -i :6274  # Inspector UI port
$lsof -i :6277  # Proxy server port

Firewall software may block localhost connections. Temporarily disable firewalls to test, then add exceptions for the Inspector ports. Some antivirus programs also interfere with local process communication.

Server Process Crashes

Your server crashes immediately upon connection, often due to unhandled exceptions during initialization. The Inspector captures stderr output, making it valuable for debugging:

// Add error handling to your server initialization
try {
  await server.connect(transport);
} catch (error) {
  console.error("Failed to initialize MCP server:", error);
  process.exit(1);
}

Check that your server handles the initialize request correctly. The Inspector sends this immediately upon connection, and servers must respond with their capabilities.

Environment Variable Issues

MCP servers receive limited environment variables by default. Missing API keys or configuration values cause subtle failures. The Inspector's environment variable panel helps diagnose these issues:

# Debug environment variables
$npx @modelcontextprotocol/inspector --env DEBUG=true --env LOG_LEVEL=verbose node server.js

Your server should validate required environment variables on startup and provide clear error messages when configuration is incomplete.

Examples

Testing a File System Server

Here's a complete example testing the official MCP filesystem server. This demonstrates the typical development workflow:

# Launch the filesystem server with Inspector
$npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/demo/projects
 
# In the Inspector UI:
# 1. Tools tab → List Tools
# 2. Select "read_file" tool
# 3. Enter path: "README.md"
# 4. Click "Run Tool"
# 5. View file contents in response

The filesystem server exposes file operations as tools. Test edge cases like missing files, directory traversal attempts, and permission errors. The Inspector shows exact error messages returned by your server.

Debugging Authentication Flow

Authentication adds complexity to MCP servers. This example shows testing a server with API key authentication:

// Server with authentication
const server = new Server({
  name: "authenticated-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

server.oninit = async () => {
  const apiKey = process.env.API_KEY;
  if (!apiKey) {
    throw new Error("API_KEY environment variable required");
  }
  
  // Verify API key with external service
  const isValid = await verifyApiKey(apiKey);
  if (!isValid) {
    throw new Error("Invalid API key");
  }
};

// Test with Inspector
// npx @modelcontextprotocol/inspector --env API_KEY=test123 node auth-server.js

Use the Inspector to test both successful authentication and failure scenarios. Verify error messages don't leak sensitive information about your authentication system.

Production servers benefit from comprehensive Inspector testing during development. Create test scripts that exercise all server capabilities, then run these through the Inspector's CLI mode as part of your deployment pipeline.

Production servers benefit from comprehensive Inspector testing during development. Create test scripts that exercise all server capabilities, then run these through the Inspector's CLI mode as part of your deployment pipeline.