Claude Code MCP 서버 연결 실패: ENOENT 등 오류 4가지 해결

MCP 서버가 안 붙으면 claude mcp list에 Failed to connect가 찍힙니다. 일부러 고장 낸 서버들을 등록해 보니, 같은 Failed to connect라도 줄 끝에 붙는 문구가 서버마다 달랐어요.

없는 실행 파일에는 ENOENT가, 경로만 틀린 URL에는 HTTP 405가 붙었죠. 그 문구가 곧 다음에 볼 곳이었습니다.

그러니 서버가 안 붙으면 그 서버 줄의 끝부터 읽으세요. ENOENT면 실행 파일 설치·경로, CONNECTION_CLOSED면 서버 명령을 터미널에서 직접 실행, HTTP 404·405면 URL 경로, 401·403이면 자격 증명입니다.

등록한 서버 이름이 목록에 아예 없다면 연결이 아니라 설정 파일 문제이니, 출력 아래 MCP config diagnostics 블록을 보면 됩니다. 다만 Windows에서는 stdio 쪽 문구로 원인을 가를 수 없었는데, 그 얘기는 stdio 절에 따로 적었습니다.

출력은 2026년 9월 17일 Ubuntu 24.04 · Claude Code 2.1.273에서 얻은 것이고, Windows 부분은 9월 30일 Windows 11 · Claude Code 2.1.283에서 직접 실행했고 10월 14일 2.1.296에서 다시 확인했습니다. 동작 규칙은 공식 문서(MCP 연결하기, MCP 참조) 기준입니다. 서버를 처음 등록하는 법은 Claude Code에 MCP 서버를 붙이는 방법에 있습니다.

상태 줄은 끝을 읽는다

테스트 환경에서 서버 셋을 등록하고 목록을 봤습니다. 제대로 도는 문서 서버, 존재하지 않는 실행 파일, 살아 있는 호스트에 경로만 틀린 URL입니다.

docs: https://code.claude.com/docs/mcp (HTTP) - √ Connected
broken-stdio: mcp-server-does-not-exist  - × Failed to connect — ENOENT: Executable not found in $PATH: "mcp-server-does-not-exist"
wrongpath: https://code.claude.com/docs/nope (HTTP) - × Failed to connect — HTTP 405: Error POSTing to endpoint: …

두 줄 다 Failed to connect이지만 볼 곳은 전혀 다릅니다. 하나는 실행 파일 설치, 하나는 URL 경로예요. 세션 안에서는 /mcp가 같은 상태를 보여 주고, 그 자리에서 재연결과 인증도 됩니다.

상태	뜻	다음에 볼 곳
✔ Connected	쓸 수 있음	도구가 없으면 환경 변수
! Connected · tools fetch failed	도구 목록을 못 받음	claude mcp get <이름>
! Needs authentication	로그인·토큰 필요	claude mcp login <이름>
✘ Failed to connect	서버가 응답 안 함	상태 뒤 문구
✘ Connection error	연결 시도가 예외	curl, 명령 직접 실행
⏸ Pending approval	승인 전 project 서버	그 폴더에서 claude
⊘ Disabled for this project	disabledMcpServers가 끔	/mcp에서 다시 켜기

기호 모양은 터미널마다 다릅니다. 일부 구형 Windows 콘솔(예: Windows 10 기본 콘솔)은 √·×로 그리고, 위 Ubuntu 터미널에서도 √·×였어요. 모양이 달라도 같은 상태입니다.

실패 문구는 Claude Code 2.1.219부터 붙습니다. 그보다 낮은 버전은 상태만 보여 주니 먼저 업데이트하세요.

✘ Connection error에는 어느 버전에서도 문구가 붙지 않는데, 거기 찍힐 예외 문자열에 비밀이 담길 수 있는 서버 URL이 들어갈 수 있어서입니다. 이때는 바로 HTTP 절의 curl 확인으로 넘어가면 됩니다.

stdio 서버는 Command 줄을 직접 실행해 본다

claude mcp get은 실패 문구를 Issue: 줄에, 실제로 실행하는 명령을 Command:·Args: 줄에 보여 줍니다.

broken-stdio:
  Status: × Failed to connect
  Issue: ENOENT: Executable not found in $PATH: "mcp-server-does-not-exist"
  Type: stdio
  Command: mcp-server-does-not-exist
  …

Command:와 Args:를 터미널에 그대로 쳐 보는 게 가장 빠릅니다. 서버가 내는 진짜 오류가 그대로 보이고, 명령이 시작해 입력을 기다리면 서버 자체는 동작하는 거예요.

ENOENT: Executable not found in $PATH

등록한 명령의 실행 파일을 $PATH에서 못 찾았다는 뜻입니다. 서버 코드가 아니라 명령 이름·설치·경로 문제예요. Command: 줄 이름을 셸에서 실행해 보고, 같은 “없음” 오류가 나면 그 도구를 설치하거나 절대 경로로 다시 등록하세요.

CONNECTION_CLOSED: Connection closed

실행 파일은 찾았는데 연결이 닫혔다는 뜻입니다. 시작하자마자 끝나는 서버(claude mcp add dies -- node -e "process.exit(1)")로 직접 재현했습니다.

같은 명령을 터미널에서 실행해 그 프로그램이 왜 끝나는지 보세요. claude mcp get에 나온 명령이 입력한 것과 다르다면, 등록할 때 서버 명령 앞의 --를 빠뜨렸을 가능성이 큽니다.

Windows에서는 없는 실행 파일도 CONNECTION_CLOSED

Windows에서는 상태 문구만으로는 원인을 가를 수 없습니다. 없는 실행 파일도 곧바로 죽는 프로세스와 똑같이 CONNECTION_CLOSED로 찍히니, 디버그 로그를 보세요.

Windows 11 · Claude Code 2.1.283에서 같은 실험을 해 보니 ENOENT가 나오지 않더라고요. 10월 14일 2.1.296에서 다시 등록해 봐도 같았습니다.

broken-stdio: mcp-server-does-not-exist  - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed
dies: node -e process.exit(1) - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed

절대 경로로 없는 파일(C:\nope\server.exe)을 등록해도 같았습니다. npx --version을 그대로 등록한 것과 cmd /c npx --version으로 감싼 것도 둘 다 CONNECTION_CLOSED로, 다르게 표시되지 않았어요(--version만 찍고 끝나는 명령이라 닫히는 것이 정상입니다).

세션 안의 /mcp도 둘을 가려 주지 않습니다. 목록에는 ✘만 찍히고, 서버를 골라 들어간 상세 화면에도 failed와 명령만 있고 Issue: 문구는 없어요.

목록 아래 안내대로 디버그 로그를 남기면 갈립니다. claude --debug-file mcp-debug.txt로 세션을 한 번 띄우고 파일에서 서버 이름을 찾았어요.

MCP server "broken-stdio": stderr of the stdio server before restarting it: 'mcp-server-does-not-exist'��(��) ���� �Ǵ� �ܺ� ����, …
MCP server "broken-stdio" Connection failed (CONNECTION_CLOSED): Connection closed
MCP server "dies" Connection failed (CONNECTION_CLOSED): Connection closed

없는 실행 파일 쪽에만 stderr 줄이 붙고, 깨진 글자는 명령 프롬프트의 '…'은(는) 내부 또는 외부 명령, … 오류가 코드 페이지가 어긋난 채 찍힌 것입니다. cmd의 오류가 나온다는 건 Windows에서는 명령이 cmd를 거쳐 실행된다는 뜻으로 보이고, cmd 자체는 있으니 ENOENT 대신 연결이 닫힌 것으로 나오는 거죠. 곧바로 죽는 dies에는 stderr 줄이 없었습니다.

Windows라면 디버그 로그의 stderr 줄을 보거나, Command: 줄 명령을 직접 실행해 가리세요.

한국어 Windows PowerShell에서는 없는 명령에 'mcp-server-does-not-exist' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다.로 시작하는 오류가, 명령 프롬프트(cmd)에서는 'mcp-server-does-not-exist'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.가 나왔습니다.

이렇게 나오면 설치·경로 문제이고, 명령이 시작해 입력을 기다리면 서버 쪽을 보면 됩니다.

HTTP 서버는 curl 응답 코드로 가린다

Claude Code 밖에서 URL에 직접 요청을 보내 봅니다. PowerShell에서는 curl이 Invoke-WebRequest의 별칭이므로 curl.exe로 부르세요.

curl -s -o /dev/null -w "%{http_code}\n" -I https://code.claude.com/docs/nope

404

응답	뜻	고칠 곳
404, 405	서버는 살아 있음	URL 경로
401, 403	살아 있고 인증 필요	자격 증명
000, 응답 없음	닿지 않음	호스트, 네트워크

404·405가 “살아 있다”인 이유는 POST만 받는 MCP 엔드포인트가 많아서입니다. 위 404는 틀린 경로에 HEAD를 보낸 결과이고, 같은 URL에 Claude Code가 보낸 POST는 405를 받았습니다. 맞는 경로(/docs/mcp)에 보내면 200이 오고, 닿지 않는 호스트로 보내 보니 000이 찍히며 curl이 실패했어요.

경로가 틀렸다면 claude mcp get <이름>으로 등록된 URL을 꺼내 서버 문서의 엔드포인트와 맞춰 보고, 지웠다가 올바른 URL로 다시 추가하면 됩니다.

인증 쪽에는 함정이 하나 있습니다. 서버가 401·403으로 답하면 보통 Needs authentication으로 표시되는데, headers나 headersHelper로 Authorization 헤더를 직접 넣어 둔 서버는 Failed to connect로 나옵니다. 이때 고칠 것은 로그인 흐름이 아니라 직접 넣은 그 값이에요.

로그인이 필요한 서버는 셸에서 claude mcp login <이름>(v2.1.186 이상)이나 세션의 /mcp로 처리합니다. 비대화형 모드(-p)에는 /mcp 패널이 없어 Claude Code가 로그인 흐름을 대신 돌려 주지 못합니다.

목록에 이름이 없으면 진단 블록부터

서버 줄 자체가 없으면 연결이 아니라 설정을 못 읽은 것입니다. .mcp.json에 서버 넷을 적되 하나는 url을 빼고, 하나는 값이 없는 ${MY_API_TOKEN}을 헤더에 쓰고, 하나는 토큰 끝에 줄바꿈을 남겨 두고 목록을 봤습니다.

good: https://code.claude.com/docs/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
needs-var: …
pasted-token: …

MCP config diagnostics ‼
 ├ [Warning] [broken-entry] mcpServers.broken-entry: Skipped — invalid MCP server config for "broken-entry": url: Invalid input
 ├ [Warning] [needs-var] mcpServers.needs-var: Missing environment variables: MY_API_TOKEN
 └ [Warning] [pasted-token] mcpServers.pasted-token: Leading or trailing whitespace in: headers.Authorization

넷을 적었는데 목록에는 셋만 나왔습니다. 나머지 두 경고는 서버가 로드는 된다는 점이 함정이에요. 증상만 보면 설정 오류가 아니라 인증 실패처럼 보이거든요.

Skipped — invalid MCP server config for "<이름>"

그 항목이 형식에 맞지 않아 건너뛰었다는 뜻입니다. 위 예에서는 HTTP 서버에 url이 없었죠. 경고가 짚은 필드를 채우면 됩니다.

다른 서버는 정상 로드되니, 목록에 보이는 서버가 있다고 파일 전체가 온전한 것은 아닙니다.

Missing environment variables: <이름>

${VAR}가 설정되지 않은 변수를 가리키고 :-기본값도 없는 경우입니다. 서버는 ${VAR} 글자를 펼치지 않은 채 로드되므로 인증이 계속 실패해요.

Claude Code를 실행할 셸에 그 변수를 설정하거나 값을 직접 넣으세요. ${VAR:-기본값}처럼 기본값을 달아 둘 수도 있습니다.

Leading or trailing whitespace는 값 앞뒤에 보이지 않는 공백이 있다는 뜻입니다. 토큰을 붙여넣다 줄바꿈이 딸려 오는 경우가 흔하니, 토큰을 붙인 뒤 인증이 실패하면 이 경고부터 찾아보세요. 같은 블록은 같은 이름을 서로 다른 엔드포인트로 여러 범위에 등록한 경우와 workspace·claude-in-chrome·computer-use 같은 내장 서버용 예약 이름도 경고합니다.

진단 블록이 비어 있는데 이름이 안 보이면 파일 바깥을 봅니다.

• 다른 프로젝트에서 추가했다: local 범위는 추가한 프로젝트(git 저장소 루트, 저장소가 아니면 그 디렉터리)에 묶입니다.
• 읽지 않는 파일에 적었다: 읽는 파일은 ~/.claude.json과 프로젝트의 .mcp.json입니다. ~/.claude/.mcp.json, ~/.claude/mcp.json, %APPDATA%\Claude\mcp.json 같은 경로는 읽지 않습니다(이 목록이 전부는 아닙니다).
• 세션을 다시 시작하지 않았다: .mcp.json은 세션 시작 때 읽습니다.

Connected인데 도구가 없거나 늦게 뜰 때

/mcp에서 그 서버를 골라 도구 목록을 보세요. 비어 있다면 서버는 시작됐지만 도구를 등록하지 않은 것이고, 대개 API 키 같은 필수 환경 변수가 없어서입니다. 변수는 claude mcp add의 --env KEY=value나 .mcp.json 항목의 env로 넘기고, 무엇이 필요한지는 서버 문서를 봅니다.

시작이 느린 서버도 있습니다. 기본 시작 대기 시간은 30초인데, stdio 서버의 첫 실행은 npx가 패키지를 내려받느라 느려서 첫 확인에서 Failed to connect가 나왔다가 내려받기가 끝나면 Connected로 바뀔 수 있어요. 잠시 뒤 다시 확인하고, 모자라면 대기 시간을 밀리초로 늘립니다.

MCP_TIMEOUT=60000 claude                    # macOS·Linux
$env:MCP_TIMEOUT = "60000"; claude          # PowerShell

알아 두면 덜 헤매는 동작도 몇 가지 있습니다.

• 자동 재시도: HTTP·SSE 서버의 첫 연결이 5xx, 연결 거부, 타임아웃 같은 일시적 오류로 실패하면 최대 세 번 다시 시도합니다. 연결 뒤 tools/list 같은 요청도 일시적 오류면 최대 세 번 다시 시도합니다.
• Claude가 실패를 아는지: 기본으로 켜져 있는 tool search가 있으면 Claude Code가 어느 서버가 왜 실패했는지 Claude에게 알려 주어, Claude가 답에서 실패를 말합니다. tool search가 없는 구성에서는 알려 주지 않습니다.
• 출력이 잘림: 연결 문제가 아니라 별도 한도입니다. 도구 출력이 1만 토큰을 넘으면 경고가 뜨고, 기본으로 2만 5천 토큰까지만 받습니다. 한도는 MAX_MCP_OUTPUT_TOKENS로 올리고, 경고 기준선은 고정입니다.

다른 사람들이 겪은 문제

공개 이슈 두 건도 같은 곳을 가리킵니다.

• marktarry-mobysoft는 2026년 9월 11일 이슈 #93595에서, 플러그인이 정의한 HTTP 서버의 Authorization 헤더 속 ${VAR}가 2.1.260에서 빈 값으로 풀려 401을 받는다고 보고했습니다. 같은 설정이 2.1.223과 2.1.247에서는 연결됐고, 같은 셸에서 토큰을 직접 넣은 요청은 200을 받았다고 적었습니다. 오류 문구가 “토큰을 확인하라”는 쪽으로 몰아가도, 자격 증명을 Claude Code 밖에서 따로 검증해 보는 단계가 값을 하는 경우예요.
• rupjae는 2026년 2월 8일 이슈 #24057에서 설정을 바꿀 때마다 세션을 다시 시작해야 한다며 자동 반영을 요청했습니다(v2.1.36, macOS, stdio 자체 제작 서버). 새 서버 하나에 하루 세 번 재시작했고, 첫 번째 이유로 설정을 엉뚱한 파일에 적었던 것을 들었습니다.

두 이슈 모두 9월 17일 확인 시점에 열려 있었습니다.

마치며

이번에 고장 낸 서버들을 보면서, 실패 표시는 같아도 줄 끝의 문구가 다음에 볼 곳을 정한다는 걸 확인했습니다. 다만 Windows에서는 그 문구마저 ENOENT와 CONNECTION_CLOSED를 가려 주지 못했으니, stdio 서버라면 운영체제에 상관없이 통하는 방법은 결국 Command: 줄 명령을 직접 쳐 보는 것이에요. 목록에 이름이 없거나 인증만 계속 실패한다면 진단 블록이 답을 갖고 있는 경우가 많고요.

지금 안 붙는 서버가 있다면 claude mcp get <이름>을 실행해 Issue:와 Command: 두 줄부터 확인해 보세요. 서버 문제가 맞는지, 도구나 사용량 한도 쪽인지부터 가르고 싶다면 증상으로 어느 층에서 막혔는지 가르는 순서를 이어서 보면 됩니다.