Skip to content

Test an MCP server

Last reviewed October 23, 2026

Test the server on its own before an agent touches it. When an agent is in the loop you cannot tell whether a failure is your server, the client's configuration or the model's choice, and you will waste an evening finding out. The order that saves time: the Inspector first, then one real client, with the logs open.

Try it in the MCP Inspector

The MCP Inspector is the official test client. It runs through npx with nothing to install, and needs Node 22.19 or later (Inspector docs). Give it the command that starts your server:

shell
# Opens a page in your browser where you can list and call the tools
npx @modelcontextprotocol/inspector node server.mjs

# The same from the command line, for scripts and CI
npx @modelcontextprotocol/inspector --cli node server.mjs --method tools/list
npx @modelcontextprotocol/inspector --cli node server.mjs \
  --method tools/call --tool-name add --tool-arg a=2 --tool-arg b=3

For the Python server, swap node server.mjs for uv run server.py (or .venv/bin/python server.py without uv). A remote server takes --server-url https://example.com/mcp --transport http instead of a command.

The Inspector speaks the 2025 protocol unless you tell it otherwise, and real clients are split between the two. Run your checks in both eras:

shell
npx @modelcontextprotocol/inspector --cli --protocol-era modern node server.mjs --method tools/list
npx @modelcontextprotocol/inspector --cli --protocol-era legacy node server.mjs --method tools/list

A server that passes in one era and fails in the other was almost certainly started by hand rather than with the SDK's helper (see serveStdio on the build step). The command-line form is also your regression test: put the tools/list line in CI and a broken release never reaches anyone.

Add it to Claude Code

shell
# Everything after -- is the command that starts your server
claude mcp add add-numbers -- node /absolute/path/to/server.mjs

# A Python server set up with uv, with an environment variable it needs
claude mcp add add-numbers -e API_KEY=your-key -- uv --directory /absolute/path/add-numbers run server.py

# Check it
claude mcp get add-numbers

The -- matters: options before it belong to Claude Code, everything after it is passed to your server untouched. By default the server is added for you, in this project only. --scope project writes it to a .mcp.json file your team shares through the repository, and --scope user makes it available in every project (Claude Code MCP docs). Inside a session, /mcp shows whether it connected. For a uv project, --directory tells uv where the project is, since the client will not start it from that folder.

Add it to Codex

shell
codex mcp add add-numbers -- node /absolute/path/to/server.mjs

That writes an entry in ~/.codex/config.toml, which you can also edit directly (Codex MCP docs):

~/.codex/config.toml
[mcp_servers.add-numbers]
command = "node"
args = ["/absolute/path/to/server.mjs"]

Read the logs

Your server's own messages go to stderr, and each client keeps them somewhere. Claude Desktop writes a general mcp.log and one mcp-server-NAME.log per server, in ~/Library/Logs/Claude on macOS and ~/.config/Claude/logs on Linux (official tutorial). Watch them while you test:

shell
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Why won't it connect?

The failures almost everyone meets first, and what fixes them:

  • A relative path. The client starts your server from its own working directory, not yours. Use absolute paths for the program and for the file it runs.
  • Something printed to stdout. One stray console.log or print breaks the message stream, and the client usually reports it as a vague connection error. Send everything to stderr.
  • A missing environment variable. Your shell's variables do not follow the server into the client. Pass the ones it needs explicitly, with -e for Claude Code or --env for Codex.
  • A tutorial from before July 2026. from mcp.server.fastmcp import FastMCP fails on the current Python SDK, and @modelcontextprotocol/sdk is the previous TypeScript package. Match the code on the build step.
  • An old runtime. The TypeScript SDK needs Node 20 or later, the Inspector 22.19 or later, the Python SDK 3.11 or later.

Building something else? See the guides to a skill and a plugin or marketplace.