Claude Code 에 MCP 서버를 붙이고 「연결 안 됨」 진단하기
도구 하나짜리 stdio MCP 서버를 만들어 Claude Code 프로젝트 범위로 붙이고, 승인 대기·명령 경로 오타·.mcp.json 문법 오류·stdout 로그의 증상과 확인 방법을 정리합니다.
stdio MCP 서버를 .mcp.json 으로 붙이고 연결 실패 증상을 원인별로 확인합니다.
[1] SDK 를 설치하고 두 수를 더하는 add 도구 하나짜리 서버를 만듭니다.
$ 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] 프로젝트 범위로 등록합니다. --scope project 는 현재 폴더의 .mcp.json 에 쓰며(기본값 local 과 user 는 ~/.claude.json), 경로는 절대 경로로 적습니다.
$ 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] 연결 상태를 봅니다. 프로젝트 범위 서버는 처음에 승인을 받아야 붙습니다.
$ claude mcp listChecking MCP server health… hello: node ~/project/server.mjs - ⏸ Pending approval (run `claude` to approve)[4] 비대화형으로 실제 연결을 확인합니다. claude -p 는 승인 창이 없어 프로젝트 범위 서버를 묻지 않고 불러옵니다. 설정 파일을 명시해 이 서버만 씁니다.
$ 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] 실패 ①: 명령 경로 오타. command 를 nod 로 바꾸고 같은 방법으로 돌립니다. 원인은 디버그 로그에 남습니다.
$ 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] 실패 ②: .mcp.json 문법 오류. 마지막 항목 뒤에 쉼표를 남깁니다("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] 실패 ③: stdout 에 로그 찍기. 서버 시작부와 도구 안에 console.log("starting hello server"), console.log({ tool: "add", a, b }) 를 넣습니다. MCP 사양은 stdio 서버가 stdout 에 MCP 메시지 외의 것을 쓰면 안 된다고 합니다(「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] 정리합니다. 등록을 지우고 확인합니다.
$ 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.