MCP 서버 연결이 안 될 때 확인 순서 5단계

MCP(Model Context Protocol) 서버를 설정 파일에 추가했는데 클라이언트에서 도구가 보이지 않거나 연결 실패가 뜨는 경우, 원인은 대부분 몇 가지로 좁혀집니다. 이 글은 그 원인들을 자주 발생하는 순서대로 확인하는 방법을 정리합니다.

글에 나오는 에러 출력은 Node.js v22.14.0, Windows 11 환경에서 각 실패 상황을 그대로 만들어 직접 재현한 것입니다.

확인 1. 설정 파일이 유효한 JSON인가

허무하지만 가장 흔한 원인입니다. MCP 설정 파일은 표준 JSON이라 주석과 trailing comma를 허용하지 않는데, JavaScript 객체를 쓰던 습관대로 마지막 속성 뒤에 쉼표를 남기면 파일 전체가 읽히지 않습니다.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
    }
  }
}

위 설정(4번째 줄 끝 쉼표)을 파싱하면 이런 에러가 납니다.

SyntaxError: Expected double-quoted property name in JSON
at position 68 (line 5 column 5)

재현해 보니 에러가 쉼표(4번째 줄)가 아니라 다음 줄(line 5)을 가리킵니다. 파서는 쉼표 뒤에 또 다른 속성 이름이 올 것으로 기대하기 때문에, 문제의 원인이 아니라 기대가 깨진 위치를 알려주는 것입니다. 에러가 가리키는 줄만 들여다보면 멀쩡해 보이는 이유가 이겁니다. 작은따옴표를 쓴 경우도 마찬가지로 파싱 단계에서 실패합니다.

SyntaxError: Expected property name or '}' in JSON at position 2

클라이언트에 따라 이런 파싱 에러를 화면에 보여주지 않고 조용히 서버 목록만 비워두는 경우가 있어서, JSON이 깨진 줄 모르고 다른 원인을 찾아 헤매기 쉽습니다. 설정을 수정했는데 반응이 없다면 JSON 유효성부터 확인하는 것이 빠릅니다.

확인 2. command가 그 컴퓨터에서 실행되는가

JSON이 유효하다면 다음은 command입니다. 클라이언트는 설정의 command를 자식 프로세스로 실행하는데, 그 명령이 컴퓨터에 없으면 이런 에러가 납니다.

Error: spawn mcp-server-that-is-not-installed ENOENT

ENOENT는 “그런 파일이나 명령을 찾을 수 없다”는 OS 에러 코드입니다. MCP 서버 자체의 문제가 아니라, 서버를 실행하는 명령을 찾지 못한 것입니다. 터미널을 열고 설정에 적은 command를 그대로 실행해 보면 바로 확인됩니다. 터미널에서 안 되는 명령은 MCP 설정에서도 안 됩니다.

터미널에서는 되는데 클라이언트에서만 안 된다면, 클라이언트가 터미널과 다른 PATH 환경에서 실행됐을 가능성이 있습니다. GUI 앱은 셸 프로필(.bashrc, .zshrc)의 PATH 설정을 물려받지 않는 경우가 있기 때문입니다. 이때는 command에 실행 파일의 절대 경로를 적는 것이 가장 확실합니다.

확인 3. Windows라면: npx가 있는데도 ENOENT가 나는 경우

Windows에서 가장 헷갈리는 케이스입니다. 같은 컴퓨터에서 연달아 실행한 재현 결과를 먼저 보겠습니다.

--- spawn("npx") 직접 실행
Error: spawnSync npx ENOENT

--- 셸을 통해 실행 (shell: true)
works, version: 10.9.2

npx 10.9.2가 분명히 설치되어 있는데, 직접 spawn하면 ENOENT가 납니다. 이유는 Windows의 npx가 실행 파일이 아니라 npx.cmd라는 배치 스크립트이기 때문입니다. 배치 스크립트는 cmd.exe를 통해서만 실행할 수 있는데, 프로세스를 셸 없이 직접 만드는 클라이언트에서는 npx라는 이름의 실행 파일을 찾다가 실패하는 것입니다.

해결 방법은 cmd를 통해 실행하도록 설정을 바꾸는 것입니다.

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp"]
    }
  }
}

클라이언트에 따라 이 래핑을 자동으로 처리해 주는 경우도 있으므로, "command": "npx"가 그대로 동작한다면 굳이 바꿀 필요는 없습니다. ENOENT가 날 때 시도하는 해결책입니다. npm, pnpm, yarn도 같은 이유로 같은 증상이 나타납니다.

확인 4. 로컬 서버와 원격 서버 설정을 섞지 않았는가

MCP 서버는 실행 방식이 두 가지입니다.

한 서버 항목에는 둘 중 하나만 있어야 합니다. command와 url을 함께 적거나, type: "stdio"인데 url만 적는 식의 조합은 클라이언트가 어느 쪽으로 연결해야 할지 판단할 수 없게 만듭니다. 원격 서버의 url은 http:// 또는 https://로 시작해야 합니다.

확인 5. API key를 env로 넘겼는가

서버가 실행은 되는데 도구 호출이 실패한다면, 서버가 요구하는 API key나 토큰이 전달되지 않았을 가능성이 있습니다. MCP 서버 프로세스는 설정의 env 항목으로 명시한 환경변수만 확실하게 전달받는다고 생각하는 것이 안전합니다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

설정 파일에 실제 key를 적게 되므로, 이 파일을 저장소에 커밋하거나 다른 사람과 공유하지 않도록 주의해야 합니다.

구조 문제는 브라우저에서 바로 확인

확인 1과 4에 해당하는 문제 — JSON 문법, command/url/type 필드 구조 — 는 Stellar Brief의 MCP Config Validator에 설정을 붙여넣으면 바로 확인할 수 있습니다. JSON 오류는 몇 번째 줄이 문제인지 짚어주고, 서버별로 필드 구조를 검사합니다. 입력한 설정은 브라우저에서만 처리되며 서버로 전송되지 않습니다. 다만 API key가 포함된 설정이라면 key 값을 지우고 붙여넣는 것을 권합니다.

command가 실제로 실행되는지(확인 2·3)는 웹 도구가 검사할 수 없는 영역이므로, 위에서 설명한 대로 터미널에서 직접 확인해야 합니다.

순서가 중요한 이유

다섯 단계를 굳이 순서대로 확인하라고 쓴 이유가 있습니다. 이번에 실패 상황들을 재현하면서 분명해졌는데, 뒤 단계의 증상은 앞 단계가 망가져도 똑같이 나타납니다. JSON이 깨져도 “도구가 안 보이고”, command를 못 찾아도 “도구가 안 보입니다”. 증상만 보고 원인을 맞히기 어려운 구조라서, 앞에서부터 하나씩 걸러내는 것이 결과적으로 가장 빠른 길입니다. MCP 연결 문제는 “서버가 이상하다”보다 “서버까지 도달하지 못했다”인 경우가 대부분이라는 점을 기억해 두면 헤매는 시간이 줄어듭니다.