How to test an MCP server with the MCP Inspector

Run the Inspector using npx with the -y flag and pass your server command as arguments. The Inspector starts your server as a child process and connects to it via stdio. It then opens a browser-based UI where you can interact with your server.

1# For a TypeScript server using tsx
2npx -y @modelcontextprotocol/inspector tsx src/index.ts
3
4# For a compiled TypeScript server
5npx -y @modelcontextprotocol/inspector node dist/index.js
6
7# For a Python server
8npx -y @modelcontextprotocol/inspector python server.py
9
10# For a Python server using uv
11npx -y @modelcontextprotocol/inspector uv run server.py

The Inspector UI has several panels. The left sidebar shows your server's capabilities organized by type: Tools, Resources, and Prompts. The main panel shows the interaction area where you fill in parameters and see results. The bottom panel shows raw JSON-RPC messages. The connection status indicator at the top shows whether your server is connected and responding.

Click on a tool in the sidebar to open it. The Inspector displays the tool's description and input schema. Fill in the parameter fields — the Inspector shows the parameter types and descriptions from your Zod schemas. Click 'Run Tool' to send a tools/call JSON-RPC request to your server. The response appears in the main panel, and the raw JSON-RPC messages appear at the bottom.

1// Example: testing a 'get_weather' tool
2// 1. Click 'get_weather' in the Tools list
3// 2. Fill in the 'city' parameter: "tokyo"
4// 3. Click 'Run Tool'
5// 4. See the response:
6//    "Weather in Tokyo: 22°C, Clear sky, 55% humidity"
7// 5. Check the JSON-RPC tab to see the raw request/response

Click on a resource in the sidebar. For static resources, click 'Read Resource' to fetch the data. For resource templates with URI parameters, fill in the parameter fields first. The Inspector shows the resource contents including the MIME type and raw data. This is useful for verifying that your resources return the expected data format.

1// Example: testing a 'weather://cities' resource
2// 1. Click 'weather://cities' in the Resources list
3// 2. Click 'Read Resource'
4// 3. See the JSON response with city data
5// 4. Verify MIME type is 'application/json'

The bottom panel of the Inspector shows every JSON-RPC message exchanged between the Inspector (acting as the client) and your server. This includes the initialization handshake, tool calls, resource reads, and error responses. When something goes wrong, the raw messages reveal exactly what the server received and what it returned. Look for malformed responses, missing fields, or unexpected error codes.

Intentionally provide invalid inputs to your tools to verify error handling. Try empty strings, missing required parameters, out-of-range values, and completely wrong data types. Your server should return responses with isError: true and helpful error messages. The Inspector shows how the error propagates through the protocol.

1// Error handling tests to try:
2// 1. Call get_weather with city: "" (empty string)
3// 2. Call get_weather with city: "nonexistent_city"
4// 3. Call calculate with b: 0, operation: "divide" (division by zero)
5// 4. Omit required parameters entirely

If your server needs environment variables (API keys, database URLs), pass them using the -e flag or set them in your shell before running the Inspector. The Inspector forwards environment variables to the server process it spawns.

1# Pass environment variables with -e flag
2npx -y @modelcontextprotocol/inspector -e API_KEY=sk-abc123 tsx src/index.ts
3
4# Or set them in your shell first
5export API_KEY=sk-abc123
6npx -y @modelcontextprotocol/inspector tsx src/index.ts