Claude Code MCP 서버 연결 오류 해결법

트러블슈팅

MCP 서버를 처음 연결하다 보면 설정 파일 오타, 경로 오류, 실행 환경 불일치 같은 문제로 막히기 쉬워요.
이 글에서는 대표적인 연결 실패 원인과 에러별 대응법, 그리고 연결 성공 후 확인해야 할 사항까지 한번에 정리합니다.

📌 3줄 요약

• MCP 서버 연결 실패의 대부분은 설정 파일 경로 오류와 실행 환경 불일치가 원인이에요.
• 설정 파일 점검 체크리스트 4단계와 에러 메시지별 대응법을 알면 빠르게 해결할 수 있어요.
• 연결 성공 후에는 /tools로 도구 목록을 확인하고, 프로젝트별로 서버를 분리 관리하는 것이 핵심이에요.

🗂️ 목차

• MCP 서버 연결이 안 되는 대표 원인
• 설정 파일 점검 체크리스트
• 서버 실행 오류별 대응 방법
• 연결 성공 후 확인할 것들

MCP 서버 연결이 안 되는 대표 원인

🔍 MCP란?
MCP(Model Context Protocol) 서버는 Claude Code에 외부 도구나 데이터를 연결하는 통로예요. 데이터베이스 조회, 파일 관리, API 호출 같은 기능을 Claude Code 안에서 바로 쓸 수 있게 해주는 구조입니다. 쉽게 말하면 Claude Code의 능력을 확장하는 플러그인 시스템이라고 이해하면 돼요. 예를 들어 GitHub MCP 서버를 연결하면 Claude Code가 직접 이슈를 만들거나 PR을 조회할 수 있게 됩니다.

그런데 처음 설정할 때 연결 실패를 겪는 경우가 많아요. 가장 흔한 원인은 설정 파일의 경로 오류와 서버 실행 환경 불일치입니다. 생각보다 사소한 오타 하나 때문에 몇 시간을 헤매는 분들이 정말 많아요. 저도 처음에는 에러 메시지만 보고 막막했던 기억이 있습니다.

MCP 서버 설정은 .claude/settings.json 또는 프로젝트 루트의 .mcp.json 파일에 작성해요. 이 파일에 서버 실행 명령어, 인자, 환경 변수를 JSON 형식으로 지정하는 방식입니다. .mcp.json은 프로젝트 단위로 관리되기 때문에 팀원들과 공유하기에도 편리해요. 반면 settings.json은 전역 설정이라서 모든 프로젝트에 공통으로 적용됩니다.

⚠️ 주의
설정 파일에 오타가 하나라도 있으면 서버가 아예 시작되지 않아요. 특히 Windows 환경에서는 경로 구분자(\ vs /)를 잘못 쓰는 실수가 자주 발생합니다. Windows에서는 백슬래시를 이스케이프해서 \\로 쓰거나, 슬래시 /로 통일하는 것이 안전해요. Mac이나 Linux에서 잘 되던 설정이 Windows에서 안 되는 이유가 대부분 이 경로 문제입니다.

 

💬 제가 직접 써보니, 처음 연결할 때는 반드시 터미널에서 서버를 수동으로 먼저 실행해 보는 것이 좋았어요. 서버 자체가 정상 동작하는지 확인한 뒤에 Claude Code에 등록하면 문제를 절반으로 줄일 수 있습니다. 이 한 단계만 추가해도 디버깅에 들이는 시간이 크게 줄어들어요.

설정 파일 점검 체크리스트

MCP 서버 연결 오류가 나면 가장 먼저 설정 파일을 열어야 해요. 아래 항목을 하나씩 확인하면 대부분의 문제를 잡을 수 있습니다. 체크리스트를 순서대로 따라가면 빠뜨리는 항목 없이 점검할 수 있어요.

1

command 필드 점검

command 필드에 적은 실행 파일이 시스템 PATH에 등록되어 있는지 확인해요. npx, uvx, node 같은 명령어가 터미널에서 직접 실행되는지 먼저 테스트해야 합니다. 터미널에서 which npx(Mac/Linux) 또는 where npx(Windows) 명령어로 경로를 확인할 수 있어요. PATH에 없으면 절대 경로를 직접 적어주는 것도 방법입니다.

2

args 배열 점검

args 배열에 전달하는 인자 순서와 값이 정확한지 봐요. 패키지 이름을 잘못 쓰거나 버전을 명시하지 않으면 설치 단계에서 실패합니다. 특히 npx를 쓸 때는 패키지 이름 앞에 -y 플래그를 넣어야 자동 설치가 되는 경우가 있어요. 공식 문서에 나온 args 예시를 그대로 복사해서 쓰는 것이 가장 확실합니다.

3

env 필드 점검

env 필드에 API 키나 토큰 같은 환경 변수를 빠뜨리지 않았는지 확인해요. 환경 변수 값에 따옴표를 중복으로 감싸는 실수도 자주 보입니다. JSON 안에서 값을 지정할 때는 바깥의 큰따옴표만 있으면 되고, 값 자체에 따옴표를 넣으면 안 돼요. API 키에 특수문자가 포함된 경우에는 이스케이프 처리가 필요한지도 확인해야 합니다.

4

JSON 문법 검증

쉼표 누락이나 중괄호 불일치는 에디터의 JSON 검증 기능으로 바로 찾을 수 있습니다. VS Code를 쓴다면 .mcp.json 파일을 열었을 때 문법 오류가 빨간 밑줄로 표시돼요. JSON에서는 마지막 항목 뒤에 쉼표를 넣으면 안 되는데, 이 실수가 의외로 많습니다.

 

claude mcp list 명령어를 실행하면 현재 등록된 서버 목록과 연결 상태를 한눈에 볼 수 있어요. 여기서 error 표시가 나오면 해당 서버의 설정을 집중적으로 점검하면 됩니다. connected 상태가 아닌 서버는 이름 옆에 오류 메시지가 함께 표시되기 때문에 원인 파악에 도움이 돼요.

💬 제가 직접 써보니, 설정 파일을 수정한 뒤에는 Claude Code를 완전히 종료했다가 다시 시작해야 변경이 반영되었어요. 단순히 새 대화를 시작하는 것만으로는 부족한 경우가 있었습니다. /quit으로 완전히 나간 뒤 다시 claude 명령어로 실행하는 것이 확실해요.

서버 실행 오류별 대응 방법

설정 파일이 정상인데도 연결이 안 되는 경우가 있어요. 이때는 서버 프로세스 자체의 오류를 살펴봐야 합니다. 에러 메시지를 정확히 읽으면 원인의 80%는 바로 파악할 수 있어요.

에러 메시지	의미	대응 방법
spawn ENOENT	실행 파일을 찾을 수 없음	node/npx/python/uvx PATH 확인, 또는 절대 경로 사용
ECONNREFUSED	서버 미실행 또는 포트 불일치	서버 프로세스 확인, netstat으로 포트 점검, 포트 충돌 확인
timeout	서버 응답 지연	방화벽·프록시 설정 확인, VPN 해제 또는 예외 등록
INVALID_REQUEST	프로토콜 버전 불일치	MCP 서버 패키지 + Claude Code 모두 최신 버전으로 업데이트

spawn ENOENT 오류는 실행 파일을 찾을 수 없다는 뜻이에요. Node.js 기반 서버라면 node나 npx가 설치되어 있는지, Python 기반이라면 python이나 uvx가 PATH에 있는지 확인해요. NVM이나 pyenv 같은 버전 관리 도구를 쓰는 경우, 셸 환경에 따라 PATH가 달라질 수 있어서 주의가 필요해요. 이럴 때는 command 필드에 절대 경로를 직접 적어주면 확실히 해결됩니다.

ECONNREFUSED 오류는 서버가 실행 중이지 않거나 포트가 다를 때 나타나요. 로컬에서 서버를 별도로 띄워야 하는 타입이라면, 서버 프로세스가 살아 있는지 먼저 점검합니다. netstat 명령어로 해당 포트가 실제로 열려 있는지 확인하는 것도 좋은 방법이에요. 다른 프로그램이 같은 포트를 사용하고 있어서 충돌이 나는 경우도 종종 있습니다.

timeout 오류는 서버가 응답은 하지만 너무 느릴 때 발생해요. 네트워크 기반 MCP 서버를 쓰는 경우, 방화벽이나 프록시 설정이 연결을 막고 있을 수 있습니다. 회사나 학교 네트워크에서 작업할 때 특히 이 문제가 자주 나타나요. VPN을 끄거나 프록시 예외 목록에 로컬 주소를 추가하면 해결되는 경우가 많습니다.

INVALID_REQUEST 오류는 서버와 클라이언트 간 프로토콜 버전이 맞지 않을 때 나와요. MCP 서버 패키지를 최신 버전으로 업데이트하면 해결되는 경우가 많습니다. Claude Code 자체도 최신 버전인지 함께 확인하는 것이 좋아요. claude update 명령어로 간단히 업데이트할 수 있습니다.

 

💡 팁
디버깅할 때 가장 유용한 방법은 claude mcp serve 명령어로 서버를 직접 실행해 보는 것이에요. 이렇게 하면 서버의 표준 출력과 에러 로그를 터미널에서 바로 확인할 수 있습니다. 로그에 나오는 스택 트레이스를 읽으면 정확히 어느 지점에서 문제가 생겼는지 알 수 있어요.

💬 제가 직접 써보니, 오류 메시지만 보고 원인을 추측하는 것보다 서버를 수동 실행해서 로그를 읽는 편이 훨씬 빨랐어요. 특히 환경 변수 문제는 로그 없이는 찾기 어려운 경우가 대부분이었습니다.

연결 성공 후 확인할 것들

MCP 서버가 정상 연결되면 Claude Code 대화창에서 해당 도구를 바로 사용할 수 있어요. /tools 명령어로 현재 사용 가능한 도구 목록을 확인하는 것이 첫 번째 할 일입니다. 이 명령어 하나로 연결이 제대로 되었는지 최종 확인할 수 있어요.

도구 목록에 MCP 서버가 제공하는 함수들이 표시되면 연결이 성공한 것이에요. 목록에 나타나지 않으면 서버는 연결되었지만 도구 등록 과정에서 문제가 생긴 것이므로 서버 측 설정을 다시 봐야 합니다. 간혹 서버가 도구 목록을 반환하는 핸들러에 버그가 있는 경우도 있으니, 서버 쪽 코드도 확인해 보세요.

연결 직후에는 간단한 테스트 요청을 보내서 실제로 동작하는지 확인해요. 예를 들어 파일 시스템 MCP 서버라면 "현재 디렉토리의 파일 목록을 보여줘"라고 요청해 봅니다. 데이터베이스 MCP 서버라면 간단한 SELECT 쿼리를 실행해 보는 것이 좋아요. 이렇게 가벼운 요청으로 먼저 테스트하면 본격적인 작업 중에 오류를 만날 확률이 줄어듭니다.

🔍 권한 설정 알아두기
Claude Code는 MCP 도구를 처음 호출할 때 사용자에게 허용 여부를 묻는데, 이때 "이 세션 동안 허용"을 선택하면 반복 확인을 줄일 수 있습니다. 자주 쓰는 도구라면 .claude/settings.json의 allowedTools 항목에 추가해서 매번 승인하지 않아도 되게 설정할 수 있어요. 다만 보안이 중요한 도구는 매번 확인하는 편이 안전합니다.

⚠️ 주의
여러 MCP 서버를 동시에 연결할 수도 있어요. 다만 서버 수가 많아지면 Claude Code의 컨텍스트(context)에 도구 설명이 추가되어 사용 가능한 토큰(token) 양이 줄어드는 점을 알고 있어야 합니다. 실제로 서버를 10개 이상 연결하면 대화 길이가 짧아지는 것을 체감할 수 있어요. 그래서 프로젝트에 꼭 필요한 서버만 선별해서 등록하는 것이 중요합니다.

 

💬 제가 직접 써보니, 필요한 서버만 프로젝트별로 .mcp.json에 등록하고 전역 설정에는 공통 서버만 두는 방식이 가장 깔끔했어요. 프로젝트마다 쓰는 도구가 다르기 때문에, 불필요한 서버를 전역에 두면 매번 컨텍스트를 낭비하게 됩니다. 이 구분만 잘해도 Claude Code를 훨씬 효율적으로 쓸 수 있어요.

✍️ 마치며

MCP 서버 연결은 처음에 막막해 보이지만, 결국 설정 파일 오타, 실행 환경 경로, JSON 문법 이 세 가지로 귀결되는 경우가 대부분이에요. 체크리스트를 순서대로 점검하고, 에러 메시지를 꼼꼼히 읽으면 대부분 30분 안에 해결할 수 있습니다. 연결에 성공한 뒤에는 프로젝트별로 서버를 분리 관리해서 컨텍스트를 효율적으로 쓰는 것까지 챙겨 보세요.

#ClaudeCode #MCP서버 #MCP연결오류 #트러블슈팅 #AI코딩