Testing an MCP server with MCP Inspector

What you need

Node.js 22.19 or newer for the current version of Inspector (node --version tells you), plus whatever the server itself needs. Nothing to install: npx fetches Inspector each time. MCP Inspector has its own page on the shelf.

Test a local server in the browser

Put the command your config runs after the Inspector command:

npx @modelcontextprotocol/inspector npx -y @playwright/mcp@latest

1. Open the local address Inspector prints in your browser.
2. Click Connect. A failure here means the server did not start: the error panel shows why.
3. Open Tools and list them. Check you see the tools the server promises.
4. Pick a harmless tool, fill in its inputs and run it. Read the result, or the error it returns.

Pass the keys the server needs

Give each environment variable with -e, before the server command:

npx @modelcontextprotocol/inspector -e FIRECRAWL_API_KEY=fc-your-key npx -y firecrawl-mcp

Inspector keeps OAuth tokens and -e values in your system keychain where there is one. Without a keychain (some Linux setups, SSH sessions, containers) it writes them to ~/.mcp-inspector/secrets.json instead.

Test exactly what your app runs

Retyping a config is how typos sneak in. Point Inspector at your app's own config file and name the server; it reads the file without changing it:

npx @modelcontextprotocol/inspector --config ~/Library/Application\ Support/Claude/claude_desktop_config.json --server playwright

npx @modelcontextprotocol/inspector --config ~/.cursor/mcp.json --server playwright

This works for any file with an "mcpServers" block. If the server works here but not in your app, the app is the problem: usually a missing path or key, covered in Fixing MCP server errors.

Test a remote server

npx @modelcontextprotocol/inspector --cli https://mcp.example.com/mcp --method tools/list

Inspector works out the transport from a URL ending in /mcp (Streamable HTTP) or /sse. For any other address add --transport http or --transport sse. A key header goes in with --header "Authorization: Bearer YOUR_TOKEN". Servers that sign in with OAuth open your browser.

Test from the terminal with the CLI

Add --cli and a --method to get one answer and exit, which is quicker than the browser and works in scripts:

npx @modelcontextprotocol/inspector --cli npx -y @playwright/mcp@latest --method tools/list

npx @modelcontextprotocol/inspector --cli npx -y @modelcontextprotocol/server-everything \
  --method tools/call --tool-name echo --tool-arg message=hello

{
  "content": [
    {
      "type": "text",
      "text": "Echo: hello"
    }
  ]
}

Repeat --tool-arg key=value for each input; values are read as JSON, so count=3 is a number and options='{"a":1}' an object. Add --format json to pipe the result into jq, for example | jq -r '.result.tools[].name' to print only the tool names.

When the first run times out

The CLI gives a server 15 seconds to connect. The first time npx or uvx starts a server it downloads the package first, which can take longer, and you get "Connection timed out after 15000 ms". We hit this with Playwright. Give it longer:

npx @modelcontextprotocol/inspector --cli --connect-timeout 120000 npx -y @playwright/mcp@latest --method tools/list

Your app has the same problem on a first run, and the same fix: a longer start-up timeout, or run the command once in a terminal so the package is cached.

Reading the result

On failure the CLI also prints one line of JSON on stderr with an error code and message, so a script can tell the cases apart.

Questions