오류 MCP Server 연결 안 될 때, Claude Code에서 바로 잡는 순서

오류 MCP Server 연결 안 될 때, Claude Code에서 바로 잡는 순서

MCP Server 연결 안 될 때 제일 답답한 순간이 딱 이거죠. 방금 추가한 서버가 안 보이거나, /mcp에는 뜨는데 pending만 돌고, 로그인까지 했는데 도구 호출이 안 붙습니다. Claude Code를 자주 쓰는 사람일수록 이 구간에서 시간을 제일 많이 날리더라구요.

제가 크게 보는 건 복잡한 버그보다 설정 충돌입니다. MCP Server 연결 안 될 때는 서버 자체가 고장난 경우보다 scope, 환경변수, timeout, OAuth callback 같은 기본값에서 먼저 엇나가는 일이 더 많았거든요. 매달 구독료 내는 입장에선 이런 데서 20분씩 쓰는 게 제일 아깝습니다.

먼저 1분 체크

제일 먼저 Claude Code 안에서 /mcp를 열어 상태를 봅니다. 여기서 connected, pending, failed 중 뭐로 뜨는지만 알아도 절반은 정리돼요. Claude Code가 아예 안 뜨면 터미널에서 claude doctor, 실행은 되는데 MCP만 이상하면 세션 안에서 /doctor를 돌리는 쪽이 빠릅니다.

1. Failed to parse config가 뜰 때

MCP Server 연결 안 될 때 제일 흔한 원인 중 하나가 이 문구입니다. .mcp.json 안에서 ${API_KEY} 같은 값을 불러오는데, 실제 환경변수가 비어 있으면 Claude Code가 config 자체를 읽지 못합니다. 서버가 죽은 게 아니라 시작도 못 한 상태에 가깝죠.

팀 저장소에 .mcp.json만 공유해두고 각자 키를 안 넣은 경우가 특히 많습니다. 이럴 땐 변수 이름이 맞는지 보고, 기본값이 필요한 항목은 기본값을 같이 적는 편이 덜 막혀요.

2. 추가했는데 안 보이거나 다른 설정이 잡힐 때

Claude Code MCP는 local, project, user 세 가지 scope를 씁니다. 같은 이름의 서버가 여러 군데 있으면 local이 먼저 먹고, 그다음 project, 마지막이 user 순서로 적용됩니다. 저는 이 우선순위 때문에 예전 설정이 계속 살아 있는 경우를 꽤 봤습니다.

서버를 새로 넣었는데 반응이 이상하면 목록만 보지 말고 상세를 찍어보는 게 낫습니다. 어느 경로에 어떤 설정이 들어갔는지 바로 보이거든요.

3. pending만 돌거나 startup timeout이 날 때

이럴 때는 서버가 느린 건지, 실행 명령이 무거운 건지 먼저 갈라야 합니다. npx로 처음 띄우는 서버는 패키지 설치 때문에 시작이 늦어질 수 있어서 timeout만 늘려도 붙는 경우가 꽤 있어요.

4. OAuth 로그인 뒤에 연결이 안 이어질 때

브라우저 인증까지 끝났는데 Claude Code 쪽이 조용하면 callback 포트 문제인 경우가 많습니다. 어떤 서버는 미리 등록한 redirect URI만 받아서 랜덤 포트를 싫어하거든요. 브라우저가 자동으로 안 열리면 URL을 직접 열고, redirect 뒤에 connection error가 보이면 주소창의 전체 callback URL을 Claude Code 프롬프트에 그대로 붙여 넣는 방법이 먼저 먹힙니다.

그리고 “Incompatible auth server: does not support dynamic client registration”가 나오면 자동 등록형 서버가 아니라는 뜻입니다. 이 경우엔 client ID와 secret을 직접 넣는 쪽으로 가야 해요.

5. SSE로 붙였는데 자꾸 불안정할 때

예전 예시를 보고 SSE로 붙인 사람도 아직 있더라구요. 지금은 HTTP 서버를 쓸 수 있으면 그쪽이 낫습니다. 공식 문서도 SSE는 deprecated라고 적어놨고, 새로 추가할 때도 HTTP 예시가 더 많이 보입니다. 오래된 블로그 글 복붙하다가 여기서 한 번씩 삐끗합니다.

MCP Server 연결 안 될 때 괜히 Claude Code를 다시 설치하기보다 transport부터 바꿔보는 게 더 현실적이었어요. 특히 사내 도구나 외부 SaaS 연동은 HTTP가 덜 꼬입니다.

끝에 남는 체크리스트

MCP Server 연결 안 될 때 순서는 거의 고정입니다. /mcp로 상태 확인, claude mcp get으로 실제 설정 확인, 환경변수 확인, timeout 조정, OAuth callback 확인. 여기까지 했는데도 안 붙으면 서버 쪽 로그를 보는 단계로 넘어가면 됩니다.

대부분은 서버가 고장난 게 아니라 설정 한 줄이 어긋난 상태거든요.