---
title: "How to Test an MCP Server: MCP Inspector UI and CLI"
url: "https://mcpshelf.co/guides/test-an-mcp-server"
description: "Test any MCP server before blaming your app: start it in MCP Inspector, list its tools, call one, and read the real error. Commands for the web UI and the CLI."
updated: "2026-11-01"
site: "MCP Shelf"
---

# Testing an MCP server with MCP Inspector

By Sophie Filer · Updated 1 Nov 2026

When a server does not work in your app, you need to know whether the server or the app is at fault. MCP Inspector, the official testing tool, connects to one server on its own and shows you exactly what it offers and what goes wrong. It takes about a minute.

## 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](https://mcpshelf.co/servers/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
```

> **Watch out:** A key you exported in your terminal does not reach the server. When we tested, Inspector passed only basics such as PATH and HOME plus the -e values. Many apps behave the same way, which is why a server can work in a terminal and fail in the app.

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:

macOS, Claude Desktop:

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

Cursor:

```
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](https://mcpshelf.co/guides/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:

List the tools:

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

Call one tool:

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

What came back when we ran it:

```
{
  "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

| CLI exit code | Meaning | What to do |
| --- | --- | --- |
| 0 | It worked | The server is fine. If your app still fails, compare its config with what you tested. |
| 1 | Usage or start-up error, such as "spawn npx ENOENT" | The command could not run. Check it is installed and spelled right. |
| 3 | The server wants authentication | Sign in, or pass the right key or header. |
| 4 | Server unreachable or timed out | Check the URL, your network, or raise --connect-timeout. |
| 5 | The tool returned an error, or does not exist | Read the message: often a bad input, or a missing permission on the account behind the key. |

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

### Is MCP Inspector the same as adding the server to my app?

No. Inspector only connects for as long as you are testing. It does not add the server to Claude, Cursor or anything else.

### Can I use MCP Inspector in CI?

Yes. The CLI mode exits with a code per kind of failure and prints JSON, so a job can start a server, list its tools and fail if one is missing.

### Do I need a newer Node.js than my server does?

Inspector itself needs Node.js 22.19 or newer. The server you test can need less; npx runs it with the same Node, so a newer one is fine for both.

---

From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt