Claude MCP Server 연결 오류 해결하고 Cursor 커스텀 도구 살리기

2026-07-27

잘 돌아가던 AI 에이전트가 갑자기 조용해진 순간

어제까지만 해도 터미널에서 알아서 파일도 읽고 브라우저 검색도 하던 Claude가 오늘 아침 갑자기 바보가 됐더라구요. 분명 설정 파일은 그대로 뒀는데, 도구 버튼 자체가 사라졌거나 실행할 때마다 빨간색 에러 메시지만 뿜어내는 현상입니다. 요즘 다들 코딩할 때 MCP(Model Context Protocol) 서버를 이것저것 붙여서 쓰시잖아요. 메모리 기능부터 깃허브 연동까지 붙여서 쓰다 보면 꼭 한 번은 먹통이 되는 타이밍이 오더군요.

이게 은근히 사람 진을 빼는 게, Claude Desktop이나 Cursor 에디터 자체의 버그가 아니라 대부분 환경 설정이나 사소한 경로 문제로 발생해서 그렇습니다. 직접 커스텀 도구를 만들어서 붙여보거나 오픈소스 서버를 가져와 돌려본 분들은 백프로 공감할 겁니다. 도대체 어디가 꼬인 건지 확인하는 방법과 빠르게 고치는 해결책을 정리해 봤습니다.

첫 번째: npx 명령어를 찾지 못하는 환경 변수 에러

설정 파일에 분명히 npx로 시작하는 명령어를 넣었는데 Claude Desktop이 해당 도구를 아예 로드하지 못하는 경우입니다. 원인은 생각보다 심플합니다. Claude Desktop이 실행될 때 사용자의 시스템 환경 변수(PATH)를 제대로 물고 올라가지 못해서 그렇거든요. 특히 맥OS나 윈도우 환경에서 Node.js를 설치한 경로를 에디터나 데스크톱 앱이 찾지 못할 때 자주 터집니다.

"code": "ENOENT",
"syscall": "spawn npx",
"path": "npx"

이럴 때는 시스템 전역 경로에 의존하는 대신 npx와 node의 절대 경로를 직접 적어주면 귀신같이 해결됩니다. 윈도우 사용자라면 보통 아래와 같은 경로에 npx.cmd 파일이 들어있구요. 설정 파일의 command 항목을 절대 경로로 지정해 줘야 안전합니다.

C:\\Program Files\\nodejs\\npx.cmd

설정 예시를 보면 확실해집니다. 아래처럼 command 부분에 환경 변수 대신 절대 경로를 직접 박아넣어 주는 식이죠. 이렇게 해주면 앱이 켜질 때 경로를 못 찾아서 헤맬 일이 전혀 없어집니다.

{
  "mcpServers": {
    "memory": {
      "command": "C:\\\\Program Files\\\\nodejs\\\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

두 번째: 윈도우 경로 백슬래시와 콤마 하나로 깨지는 JSON 설정 파일

가장 어이없으면서도 잦은 실수가 바로 claude_desktop_config.json 파일의 문법 오류입니다. 도구를 하나 새로 추가하려고 깃허브에서 복사해 온 설정을 붙여넣다 보면 마지막 줄에 콤마(,)를 남겨두거나, 윈도우 폴더 경로를 그대로 복사해서 넣다가 구문 에러를 냅니다. JSON 파일에서는 백슬래시 하나도 제대로 처리를 안 해주면 앱 자체가 켜지지 않거나 설정 전체가 초기화되더라구요.

Failed to parse config file: Unexpected token } in JSON at position 245

오류 메시지가 명확하면 다행인데, 에디터에 따라서는 그냥 에러 없이 설정 로드만 스킵해 버려서 더 찾기 어렵습니다. 해결 방법은 윈도우 경로를 넣을 때 반드시 백슬래시를 두 번씩 써서 이스케이프 처리를 해주는 겁니다. 아니면 그냥 슬래시(/)를 써도 정상적으로 인식하구요. 마지막 mcpServer 설정 블록 뒤에 콤마가 남아있는지도 확인해 보세요.

"command": "node",
"args": ["C:/Users/username/mcp-server/index.js"]

이렇게 슬래시로 통일하거나 역슬래시를 두 번 쓰는 것만으로도 파싱 에러는 거의 예방이 됩니다. 설정을 고친 뒤에는 Claude Desktop을 완전히 종료했다가 다시 켜는 걸 잊지 마세요.

세 번째: API 키나 환경 변수 누락으로 인한 세션 종료

브라우즈나 깃허브 MCP 같은 외부 서비스를 연동할 때는 반드시 API 토큰이나 인증 키가 필요합니다. 터미널에서는 정상적으로 돌던 서버가 Claude Desktop에만 올리면 죽어버리는 현상인데요. 설정 파일 내부의 env 블록에 필수 환경 변수를 넘겨주지 않아서 생기는 오류입니다.

Error: API key is required to start github MCP server

터미널은 내 로그인 세션이나 .bashrc, .zshrc에 정의된 키를 들고 있지만, 데스크톱 앱은 그 환경을 모르기 때문에 생기는 당연한 결과입니다. 이럴 때는 설정 JSON 안에 env 객체를 직접 만들고 거기에 필요한 환경 변수를 뚫어줘야 하구요. 깃허브 연동을 예로 들면 다음과 같이 작성하면 해결됩니다.

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

이렇게 env 설정을 명시해 주면 Claude Desktop이 백그라운드에서 프로세스를 띄울 때 해당 변수를 안전하게 주입해 줍니다. 토큰 유효기간이 지났거나 권한 범위가 좁은 경우에도 비슷한 에러가 나니까 에러 로그를 꼼꼼히 보시는 게 좋습니다.

연결 상태를 한눈에 모니터링하는 디버깅 팁

이것저것 다 건드려봤는데도 도구가 안 붙는다면 무작정 설정만 바꾸지 말고 로그 파일을 뒤져봐야 합니다. 윈도우 기준으로 %APPDATA%\\Claude\\logs 경로에 가보면 mcp.log 혹은 claude_desktop.log 파일이 쌓이고 있거든요. 에러 메시지 원문을 복사해서 번역기에 돌려만 봐도 어떤 파이프라인에서 막혔는지 금방 답이 나옵니다.

맥OS 유저분들은 ~/Library/Logs/Claude/ 폴더를 뒤져보시면 되구요. 로그 파일에 stderr로 찍히는 메시지들만 가려내도 쓸데없는 삽질 시간을 대폭 줄일 수 있습니다. 도구가 붙긴 했는데 가끔씩 응답이 늦어지는 건 대부분 타임아웃이나 컨텍스트 토큰 크기 문제니까, 네트워크 레이턴시도 한 번 체크해 볼 지점입니다.

단순한 챗봇을 넘어서 진짜 비서로 쓰는 방법

MCP 서버 오류를 해결하고 도구들이 정상 작동하기 시작하면 코딩 생산성이 완전히 달라지는 걸 느낍니다. 챗 창에서 바로 로컬 소스 코드를 읽어와 리팩토링을 요청하고, 수정 사항을 자동으로 빌드해 보는 흐름이 매끄럽게 연결되니까요. 월 20달러 구독료가 전혀 아깝지 않은 사용성을 보여주거든요. 설정 파일 하나 때문에 묵혀두기엔 너무 아까운 기능이니까 이번 기회에 한 번 제대로 세팅해 두시길 권합니다.