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:
# 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=3For 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:
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/listA 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
# 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-numbersThe -- 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
codex mcp add add-numbers -- node /absolute/path/to/server.mjsThat writes an entry in ~/.codex/config.toml, which you can also edit directly (Codex MCP docs):
[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:
tail -n 20 -f ~/Library/Logs/Claude/mcp*.logWhy 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.logorprintbreaks 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
-efor Claude Code or--envfor Codex. - A tutorial from before July 2026.
from mcp.server.fastmcp import FastMCPfails on the current Python SDK, and@modelcontextprotocol/sdkis 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.