Cursor MCP 연결 실패, 서버가 안 보일 때 무엇을 보나
Cursor MCP 연결 실패 시 가장 먼저 Output 패널의 MCP Logs(Mac: Cmd+Shift+U, Windows/Linux: Ctrl+Shift+U)를 확인합니다. 그다음 mcp.json 경로와 환경변수를 점검하고, 여전히 안 되면 Customize > MCPs에서 서버를 제거 후 다시 추가합니다.
이 글은 mcp.json을 이미 작성한 상태에서 서버가 목록에 뜨지 않거나 연결에 실패할 때의 진단·복구 절차만 다룹니다. 처음부터 서버를 추가하는 기본 설정 튜토리얼은 다루지 않습니다.
서버 목록에 안 뜨면 어디를 보나?
한 줄 답: mcp.json 파일 위치를 다시 확인하고, Output 패널의 MCP Logs에서 에러 메시지를 읽습니다.
Cursor는 프로젝트 단위(.cursor/mcp.json)와 글로벌 단위(~/.cursor/mcp.json) 두 곳에서 설정 파일을 읽습니다. 파일명이나 경로에 오타가 있으면 서버 자체가 목록에 나타나지 않습니다. 경로가 맞는데도 보이지 않는다면 백그라운드에서 발생한 에러를 로그로 확인해야 합니다.
확인 방법은 다음과 같습니다.
- Mac은
Cmd+Shift+U, Windows/Linux는Ctrl+Shift+U를 눌러 Output 패널을 엽니다. - 패널 우측 상단 드롭다운에서 MCP Logs를 선택합니다.
- 서버가 시작될 때 출력된 에러 메시지(명령어를 찾을 수 없음, 인증 실패 등)를 확인합니다.
이 로그에 원인이 대부분 남아 있으므로, 목록에 서버가 안 보이는 문제는 항상 이 단계에서 시작합니다.
권한·경로·환경변수는 어떻게 점검하나?
한 줄 답: 실행 명령어가 시스템 PATH에 있는지, 셸 환경변수가 Cursor에 전달됐는지, 원격 서버라면 인증 헤더가 맞는지 확인합니다.
로그에서 원인을 찾았다면 아래 세 가지 항목을 순서대로 점검합니다.
- 명령어 경로: 로컬 서버라면
mcp.json의command값(예:npx,python)이 실제로 시스템PATH에 등록되어 있는지 터미널에서 직접 실행해 확인합니다. - 환경변수: 서버가
.zshrc,.bashrc같은 셸 프로필의 환경변수에 의존한다면, 셸 프로필을 수정한 뒤 반드시 셸을 재시작(터미널을 새로 열거나 로그아웃 후 재로그인)한 다음 Cursor도 재시작해야 변수가 반영됩니다. - 인증 헤더: 원격(URL) 방식 서버는
mcp.json의headers항목에 넣은 API 키(Authorization: Bearer ...등)가 누락되거나 만료되지 않았는지 확인합니다.
셸 프로필에 환경변수를 새로 추가했다면, 그 변수는 셸이 재시작된 이후에 열린 Cursor에서만 인식됩니다. Cursor만 재시작하고 셸 프로필은 그대로면 변수가 여전히 비어 있을 수 있습니다.
재시작·캐시 초기화 순서는?
한 줄 답: 단순 재시작만으로 해결되지 않으면 Customize > MCPs에서 토글을 껐다 켜고, 안 되면 서버를 제거 후 다시 추가합니다.
설정을 고쳐도 기존 백그라운드 프로세스나 캐시 때문에 바로 반영되지 않는 경우가 있습니다. 다음 순서대로 진행합니다.
권장 순서
- 사이드바에서 Customize를 열고 MCPs 섹션으로 이동합니다.
- 문제가 있는 서버의 토글 스위치를 껐다가 다시 켭니다(enable/disable).
- 토글만으로 해결되지 않으면 해당 서버를 목록에서 **제거(Remove)**합니다.
- 셸 프로필이나 환경변수를 수정했다면, Cursor를 완전히 종료한 뒤 다시 실행합니다.
- 다시 Customize > MCPs에서 Add to Cursor로 서버를 재추가합니다.
이 순서(토글 → 제거 → Cursor 재시작 → 재추가)를 지키면 캐시나 잔여 프로세스로 인한 연결 실패를 대부분 해소할 수 있습니다.
마무리
정리하면 순서는 ① MCP Logs 확인 → ② 경로·환경변수·인증 점검 → ③ 토글/제거/재시작입니다. 서버 추가 자체가 처음이라면 기본 설정 방법은 별도의 mcp.json 작성 가이드를 참고하시고, 이 글은 연결이 이미 실패한 상태를 되돌리는 데에만 활용하시기 바랍니다.