Connect an MCP server to Claude Code and diagnose "not connected"
Add a one-tool stdio MCP server to Claude Code at project scope and read the symptoms of pending approval, a bad command path, broken .mcp.json and stdout logs.
Add a stdio MCP server through .mcp.json and check what each connection failure looks like.
[1] Install the SDK and create a server with one tool, add, that sums two numbers.
$ npm install @modelcontextprotocol/sdk zodimport { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import { z } from "zod"; const server = new McpServer({ name: "hello", version: "1.0.0" });server.tool("add", "Add two numbers", { a: z.number(), b: z.number() }, async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] }));await server.connect(new StdioServerTransport());[2] Register it at project scope. --scope project writes to .mcp.json in the current folder (the default local and user write to ~/.claude.json). Use an absolute path.
$ claude mcp add --scope project hello -- node ~/project/server.mjsAdded stdio MCP server hello with command: node ~/project/server.mjs to project configFile modified: ~/project/.mcp.json[3] Check the status. A project-scoped server must be approved before it connects.
$ claude mcp listChecking MCP server health… hello: node ~/project/server.mjs - ⏸ Pending approval (run `claude` to approve)[4] Verify the connection non-interactively. claude -p has no approval prompt, so it loads project-scoped servers without asking. Name the config file and use only this server.
$ claude -p "Use the add tool to compute 2+3 and answer with the number only" \ --mcp-config .mcp.json --strict-mcp-config --max-turns 3 --allowedTools mcp__hello__add5[5] Failure 1: mistyped command. Change command to nod and run the same way. The debug log shows the cause.
$ claude -p "say ok" --mcp-config bad2.json --strict-mcp-config --max-turns 1 \ --output-format stream-json --verbose…"mcp_servers":[{"name":"hello","status":"failed","source":"dynamic"}]…$ claude -p "say ok" --mcp-config bad2.json --strict-mcp-config --max-turns 1 --debug-file d.log$ grep 'MCP server "hello"' d.log[DEBUG] MCP server "hello": Starting connection with timeout of 30000ms[ERROR] MCP server "hello" Connection failed (ENOENT): Executable not found in $PATH: "nod"[6] Failure 2: invalid .mcp.json syntax. Leave a trailing comma after the last entry ("args": ["…/server.mjs"],).
$ claude -p "say ok" --mcp-config bad3.json --strict-mcp-config --max-turns 1Error: Invalid MCP configuration:MCP config is not a valid JSON$ claude mcp list…MCP config diagnostics ✘ [Failed to parse] Project config (shared via .mcp.json)Location: ~/project/.mcp.json └ [Error] MCP config is not a valid JSON[7] Failure 3: logging to stdout. Add console.log("starting hello server") at startup and console.log({ tool: "add", a, b }) inside the tool. The MCP spec says a stdio server "MUST NOT write anything to its stdout that is not a valid MCP message".
$ claude -p "Use the add tool to compute 2+3 and answer with the number only" \ --mcp-config bad1c.json --strict-mcp-config --max-turns 3 --allowedTools mcp__hello__add \ --debug-file d.log5$ grep 'MCP server "hello"' d.log[DEBUG] MCP server "hello": Calling MCP tool: add[ERROR] MCP server "hello" Ignoring non-JSON line on stdout: JSON Parse error: Expected '}'[DEBUG] MCP server "hello": Tool 'add' completed successfully in 22ms[8] Clean up. Remove the registration and confirm.
$ claude mcp remove hello --scope projectRemoved MCP server hello from project config$ claude mcp listNo MCP servers configured. Use `claude mcp add` to add a server.