목록 · 가이드

MCP 서버가 안 뜰 때 점검할 8가지

설정을 넣었는데 Claude에 도구가 안 보입니다. 대부분은 두 가지에서 끝납니다. 앱을 완전히 끄지 않았거나, JSON에 쉼표가 하나 잘못 들어갔거나입니다. 위에서부터 순서대로 확인하십시오. 흔한 것부터 배치했습니다.

1. 앱을 완전히 끄지 않았습니다

가장 흔한 원인입니다. 설정 파일은 앱이 시작할 때 한 번만 읽습니다. 창을 닫는 것과 앱을 끄는 것은 다릅니다.

Windows는 작업 표시줄 오른쪽 숨겨진 아이콘 영역에 Claude가 남아 있습니다. 거기서 마우스 오른쪽 버튼을 눌러 종료하십시오. macOS는 빨간 버튼으로 창을 닫아도 앱이 살아 있습니다. Cmd+Q를 누르십시오.

확실히 하려면 작업 관리자나 활성 상태 보기에서 Claude 프로세스가 없는 것까지 확인한 뒤 다시 실행하십시오.

2. JSON 문법이 깨졌습니다

두 번째로 흔합니다. 쉼표 하나 때문에 파일 전체가 무시되고, 앱은 아무 말도 하지 않습니다.

자주 나는 세 가지입니다. 마지막 항목 뒤에 쉼표를 남겼습니다. JSON은 이걸 오류로 봅니다. 항목 사이에 쉼표를 빼먹었습니다. 서버를 두 개 이상 넣을 때 자주 납니다. 따옴표가 짝이 안 맞습니다. 한글 입력기에서 " 대신 ”가 들어가는 경우가 있는데 눈으로는 거의 구분되지 않습니다.

가장 빠른 확인은 파일 내용을 통째로 복사해서 JSON 검사기에 붙여 넣어 보는 것입니다. 어디가 잘못됐는지 줄 번호로 알려 줍니다. 검사를 통과하는데도 안 되면 다음 항목으로 넘어가십시오.

3. 파일 이름이나 위치가 다릅니다

Windows 메모장으로 저장하면 claude_desktop_config.json.txt가 되는 일이 흔합니다. 확장자를 숨기는 설정이라 화면에는 안 보입니다.

탐색기 보기 설정에서 파일 확장명을 켜고 실제 이름을 확인하십시오. 저장할 때 파일 형식을 모든 파일로 바꾸면 이 문제가 생기지 않습니다.

위치도 확인하십시오. 정확한 경로는 아래와 같습니다.

4. Node.js가 없습니다

설정에 npx가 들어 있다면 Node.js가 필요합니다. 없으면 명령이 실행되지 않고 서버가 조용히 실패합니다.

터미널이나 명령 프롬프트에서 node -v를 쳐 보십시오. 버전 번호가 나오면 설치되어 있는 것입니다. 명령을 찾을 수 없다고 나오면 nodejs.org에서 LTS 버전을 설치하고 컴퓨터를 다시 시작하십시오.

설치했는데도 안 되면 앱이 npx를 못 찾는 경우입니다. 이때는 command에 npx 대신 전체 경로를 적으면 해결됩니다. macOS에서는 which npx, Windows에서는 where npx로 경로를 알 수 있습니다.

5. 경로에 역슬래시를 한 번만 썼습니다

Windows 경로를 넣을 때 나는 문제입니다. JSON에서 역슬래시는 특수 문자라 두 번 써야 합니다.

잘못된 예는 "C:\Users\이름\Documents"이고, 올바른 예는 "C:\\Users\\이름\\Documents"입니다. 슬래시 방향을 바꿔 "C:/Users/이름/Documents"로 써도 동작합니다. 이쪽이 실수가 적습니다.

6. 토큰이나 권한을 안 줬습니다

서버는 떴는데 도구를 쓰면 권한 오류가 나는 경우입니다. 설정이 아니라 서비스 쪽 문제입니다.

노션이 대표적입니다. 통합 토큰을 발급하는 것만으로는 부족하고, 연결하려는 페이지에서 따로 권한을 줘야 목록에 나타납니다. 페이지 오른쪽 위 메뉴에서 연결을 추가하십시오. 깃허브도 토큰 발급 시 필요한 범위를 체크하지 않으면 조회는 되고 쓰기는 안 되는 상태가 됩니다.

7. 사내망이 막고 있습니다

회사 노트북에서 원격 서버가 안 붙는다면 네트워크 정책일 가능성이 큽니다. 프록시나 방화벽이 외부 연결을 차단하거나, 보안 프로그램이 인증서를 가로채면 연결이 실패합니다.

같은 설정이 개인 네트워크에서는 되는지 먼저 확인하십시오. 개인 네트워크에서 된다면 설정 문제가 아니라 망 문제입니다. 이 경우 정보보안 담당자에게 해당 도메인 허용을 요청하는 것 외에 우회 방법은 없습니다. 보안 정책을 임의로 끄지 마십시오.

8. 버전이 낮습니다

설정에 커넥터 항목 자체가 안 보인다면 앱 버전 문제입니다. MCP 지원은 특정 버전부터 들어갔고, 원격 커넥터는 그보다 더 나중에 추가되었습니다.

앱을 최신 버전으로 올린 뒤 다시 확인하십시오. 자동 업데이트가 꺼져 있는 경우가 있으니 수동으로 확인하는 편이 확실합니다.

그래도 안 되면

서버를 하나만 남기고 나머지를 지운 뒤 다시 시도해 보십시오. 여러 개를 동시에 넣으면 어느 것이 문제인지 알 수 없습니다. 하나가 되면 하나씩 다시 추가하면서 어디서 깨지는지 찾으십시오.

가장 단순한 서버로 먼저 확인하는 것도 방법입니다. 파일 시스템 서버는 외부 계정이나 토큰이 필요 없어서, 이것이 되면 설정 파일 자체는 정상이라는 뜻입니다. 그러면 문제가 특정 서버 쪽에 있다는 것이 확인됩니다.

처음부터 다시 하시려면 Claude에 MCP 설치하기를 순서대로 따라 하십시오.

이어서 보기