We broke an MCP server on purpose. Here is what Claude Code showed

Our guide MCP server not showing up? is written from the Claude Code and Codex documentation. To see the statuses for ourselves, we wrote a small MCP server, added it to Claude Code with a typo in the path, and fixed it one step at a time. Everything below was run on 28 October 2026.

The setup

Host	Claude Code 2.1.311 on Windows 11
Model, for the last step	Claude Opus 5.5
Server	hello-server.mjs, about 20 lines of Node.js with no dependencies and one tool, say_hello. We wrote it for this test
Folder	An empty test folder; every server we added was removed at the end

Step 1: added to the project, but never started

We first put the server in the project's .mcp.json, with the file name misspelled as helo-server.mjs. claude mcp list showed:

hello: node …/helo-server.mjs - ⏸ Pending approval (run `claude` to approve)

What this tells you: a server in a project's .mcp.json does not run until you approve it, the first time you open the folder in an interactive claude session. Until then Claude Code does not try to start it, so a wrong path, a missing program or a bad key all look exactly the same: Pending approval. Approve it first, then read the status again.

claude mcp get hello adds where the server comes from, which helps when one name is defined in several places:

hello:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)

Step 2: started, and failed

We removed the project file and added the same misspelled server for this folder only:

claude mcp add hello -- node …/helo-server.mjs

Now Claude Code started it straight away:

hello: node …/helo-server.mjs - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed

Note what the message does not say. There is no "file not found". From Claude Code's side the program started and closed before it answered, which is all it can report.

Step 3: run the command yourself

The fastest way to the real error is to run the server's command exactly as it appears in the configuration, in a terminal:

node …/helo-server.mjs
Error: Cannot find module '…\helo-server.mjs'

That one line names the problem. The same check finds a missing node, npx or uvx, a wrong Python environment or a server that wants an environment variable it did not get. A working local server does not print an error; it waits silently for input, and you stop it with Ctrl+C.

Step 4: fixed

After removing the server and adding it again with the correct file name:

hello: node …/hello-server.mjs - ✔ Connected

Claude Code does not retry a failed local server on its own inside a running session. After a fix, choose Reconnect in /mcp, or start a new session.

Step 5: connected, and actually used

Connected is not the same as used, so we asked for the tool:

claude -p "Use the hello MCP server's tool to greet Ana. Reply with the tool's exact output."

The session log showed two steps: Claude Code first looked the tool up (ToolSearch for mcp__hello__say_hello), then called it with {"name": "Ana"}, and the answer was the tool's own text, Hello, Ana!. Claude Code can load MCP tools on demand like this instead of all at once, so the tool's name and description are what the model goes by.

We also tried the vague prompt Greet Ana. without mentioning the server. The model still found and used say_hello, because the tool's description ("Returns a greeting for a name") matched. With a less obvious description that might not happen; we did not test that.

How to check it yourself: in an interactive session, the tool call appears in the conversation with the server and tool name. In a headless run, --output-format stream-json --verbose lists every tool call. An answer without a tool call came from the model, not from your server.

What we took from it

1. Pending approval hides every other problem. Approve first.
2. Failed to connect rarely says why. Run the exact command in a terminal.
3. After a fix, reconnect, then ask for one small, known result and look for the tool call.

If you are stuck at one of these steps, send us the status and the error. Remove tokens and private data first.

Sources

• Claude Code: MCP: scopes, .mcp.json approval, claude mcp commands and statuses.
• Claude Code: headless mode: claude -p and the stream-json output.
• MCP architecture: how a client starts a local server and discovers its tools.