MCP 서버가 안 붙을 때 디버깅 체크리스트: 순서대로 따라가면 잡힌다

핵심 요약: MCP 연결 문제의 90%는 다섯 층 중 하나입니다. 순서대로 점검하세요: ① 서버가 단독 실행되는가(터미널에서 직접 실행) ② 설정 파일이 맞는가(경로·JSON 문법·명령어 위치) ③ 실행 환경 차이(클라이언트가 띄울 때의 PATH·환경변수는 내 셸과 다름 — 최다 원인) ④ 인증(토큰 만료·권한 부족) ⑤ 클라이언트 로그 확인. 특히 ③이 악명 높습니다 — 터미널에선 되는데 앱에서 안 되면 십중팔구 PATH 문제이고, 해법은 명령어를 절대 경로로 쓰는 것입니다.

이 글에서 다루는 내용: 5층 체크리스트 상세, 증상별 진단, Cursor·Claude Code별 로그 보는 곳, 예방 습관.

진단 전 30초: 증상 구분

목록에 아예 안 뜸 → 설정 파일 문제(②). 뜨는데 빨간불/연결 실패 → 서버 실행 문제(①·③). 연결됐는데 도구 호출이 실패 → 인증·권한(④) 또는 서버 내부 오류. 증상만 구분해도 절반은 좁혀집니다.

① 서버 단독 실행 테스트

클라이언트를 끼기 전에, 설정에 적은 명령을 터미널에서 그대로 실행해 보세요 (예: npx -y @모듈명). 여기서 죽으면 클라이언트 문제가 아닙니다 — 패키지 미설치, Node/Python 버전, 필수 환경변수 누락이 후보입니다. 단독 실행이 되는 것을 확인한 뒤에 다음으로 넘어가야 미궁에 안 빠집니다.

② 설정 파일 점검

흔한 실수 세 가지: JSON 문법 오류(마지막 항목 뒤 콤마가 단골 — 검증기에 넣어보면 3초), 파일 위치(전역 설정과 프로젝트 설정 중 어디에 넣었는지, 클라이언트가 어느 쪽을 읽는지), 오타(mcpServers 키 이름, 명령어 철자). 설정 방법 자체는 Cursor 편과 Claude Code 편을 참고하세요.

③ 실행 환경 차이 — 최다 원인

"터미널에선 되는데 앱에선 안 돼요"의 정체입니다. GUI 앱이 서버를 띄울 때는 내 셸의 PATH·환경변수를 물려받지 않는 경우가 많습니다. nvm으로 설치한 node, pyenv의 python, ~/.zshrc에서 export한 변수 — 전부 앱에게는 없는 것일 수 있습니다. 해법 두 가지: 명령어를 절대 경로로 쓰거나(which npx로 확인한 경로), 필요한 환경변수를 설정 파일의 env 블록에 명시하는 것. 이 항목 하나로 해결되는 사례가 체감상 가장 많습니다.

④ 인증과 권한

연결은 되는데 도구 호출이 실패하면 토큰을 의심하세요 — 만료, 권한 범위(scope) 부족, 조직 SSO 재승인 필요가 3대 원인입니다. 토큰을 새로 발급해 교체하는 게 가장 빠른 검증이고, 이때 필요 최소 권한만 주는 원칙(MCP 보안 가이드)도 함께 챙기세요.

⑤ 로그 보는 곳

Cursor는 출력 패널의 MCP 로그 채널에서, Claude Code는 --mcp-debug 플래그나 로그 출력에서 서버의 stderr를 볼 수 있습니다. 서버가 뱉는 첫 오류 메시지가 위 ①~④ 중 어디인지 알려주므로, 사실 로그를 먼저 보면 체크리스트를 건너뛸 수 있습니다 — 그런데도 ⑤가 마지막인 이유는, 로그 위치를 못 찾아 헤매는 시간에 ①~③이 끝나는 경우가 많기 때문입니다.

겪어본 사례 하나

GitHub MCP가 Cursor에서만 안 붙어서 한 시간을 쓴 적이 있는데, 원인은 nvm이었습니다. 터미널의 node는 nvm 것인데 Cursor가 띄운 프로세스는 시스템 node(구버전)를 잡아서 패키지가 죽고 있었죠. npx를 절대 경로로 바꾸니 즉시 해결 — 그날 이후 MCP 설정의 명령어는 무조건 절대 경로로 씁니다. 같은 문제로 시간을 쓰실 분들을 위해 이 글의 ③을 가장 길게 썼습니다.

자주 묻는 질문 (FAQ)

Q. 어제까지 되던 서버가 갑자기 안 돼요.

A. 설정을 안 바꿨다면 토큰 만료(④)나 패키지 자동 업데이트로 인한 호환성 문제가 유력합니다. 토큰 재발급 → 패키지 버전 고정 순으로 시도하세요.

Q. 여러 클라이언트에서 같은 서버를 쓰는데 한쪽만 안 돼요.

A. 서버는 정상이라는 뜻이니 ②(그 클라이언트의 설정 파일)와 ③(실행 환경)만 보면 됩니다. 설정을 다른 클라이언트에서 복사할 때 경로 형식이 다른 경우도 있습니다.

Q. 원격(HTTP) MCP 서버는 뭘 봐야 하나요?

A. 로컬 실행 문제(①③)가 빠지는 대신 URL 오타, 네트워크·방화벽, 인증 헤더가 후보입니다. curl로 엔드포인트가 응답하는지부터 확인하세요.

한눈에 보는 요약

단독 실행 → 설정 파일 → 실행 환경(PATH!) → 인증 → 로그. "터미널에선 되는데"는 절대 경로로, "갑자기 안 되면" 토큰부터. 이 순서만 지키면 미궁에 빠질 일이 없습니다.

함께 보면 좋은 글

Cursor에서 MCP 서버 연결하는 방법
Claude Code에 MCP 연결하기
MCP 보안 가이드

참고 자료

MCP 공식 문서
Cursor 공식 문서 (MCP)