Cursor MCP 오류 해결 — 연결 실패·인증 오류·MCP Logs 확인 방법
Cursor에서 MCP 서버가 연결되지 않거나 오류가 발생할 때 MCP Logs로 원인을 찾고, 연결 실패·인증 오류·서버 크래시를 단계별로 해결하는 방법을 정리합니다.
Cursor에서 MCP 서버가 갑자기 연결되지 않거나 “Failed to connect” 같은 오류가 나타나면, MCP Logs를 먼저 열어 에러 메시지를 확인하는 것이 가장 빠른 해결 경로입니다. 대부분의 오류는 설정 파일 문법 오류, 실행 명령 경로 문제, API 키 누락 중 하나에서 비롯됩니다. 이 글에서는 각 오류 유형별 원인과 해결 방법을 실제 예시와 함께 정리합니다.
Cursor MCP Logs란 무엇인가
Cursor는 MCP 서버를 별도 프로세스로 실행하고, 각 서버의 표준 출력·오류 출력을 MCP Logs 패널에 수집합니다. 일반 개발자 콘솔(DevTools)과 달리 MCP Logs는 서버별로 로그를 분리해 보여주기 때문에 어느 서버에서 오류가 났는지 즉시 파악할 수 있습니다.
MCP Logs 여는 방법
| 방법 | 단계 |
|---|---|
| 커맨드 팔레트 | Cmd+Shift+P (macOS) 또는 Ctrl+Shift+P (Windows/Linux) → MCP: Show Logs 입력 후 Enter |
| 상태바 | Cursor 하단 상태바의 MCP 아이콘 클릭 |
| 메뉴 | Help → Toggle Developer Tools → Console 탭에서 MCP 관련 로그 검색 |
로그 패널에는 [서버명] started, [서버명] error: ..., [서버명] exited with code 1 형태로 타임스탬프와 함께 기록됩니다.
Cursor MCP 설정 파일 구조 이해하기
오류를 진단하기 전에 설정 파일의 올바른 구조를 파악해야 합니다. Cursor의 MCP 설정은 프로젝트 루트의 .cursor/mcp.json 또는 전역 설정(~/.cursor/mcp.json)에 저장됩니다.
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "my-mcp-package"],
"env": {
"API_KEY": "your-api-key-here"
}
}
}
}
Cursor 에디터
│
├─ .cursor/mcp.json 읽기
│
├─ MCP 서버 A 프로세스 시작 ──── stdout/stderr ──▶ MCP Logs
├─ MCP 서버 B 프로세스 시작 ──── stdout/stderr ──▶ MCP Logs
│
└─ AI 채팅 요청 ──▶ MCP 서버 A/B ──▶ 외부 API/도구
자주 발생하는 오류 유형과 해결법
1. “Failed to connect” / 서버가 시작되지 않음
서버가 아예 뜨지 않는 경우로, 흔한 원인은 아래 세 가지입니다.
원인 1: JSON 문법 오류
설정 파일에 쉼표가 하나 빠지거나 따옴표가 맞지 않으면 Cursor가 파일 전체를 파싱하지 못해 모든 서버가 로드되지 않습니다.
# JSON 문법 검증 (터미널에서 실행)
cat ~/.cursor/mcp.json | python3 -m json.tool
오류가 없으면 아무 출력 없이 종료됩니다. 오류가 있으면 줄 번호와 함께 메시지가 표시됩니다.
원인 2: 실행 명령이 PATH에 없음
npx나 uvx가 PATH에 없으면 서버를 실행할 수 없습니다. Cursor는 시스템 쉘의 PATH를 그대로 상속하지 않을 수 있습니다.
# npx 경로 확인
which npx
# Node.js 버전 확인
node --version
macOS에서 nvm을 사용한다면, Cursor가 실행될 때 nvm이 초기화되지 않아 npx를 찾지 못하는 경우가 있습니다. 이때는 command에 절대 경로를 넣어야 합니다.
{
"mcpServers": {
"my-server": {
"command": "/Users/yourname/.nvm/versions/node/v20.0.0/bin/npx",
"args": ["-y", "my-mcp-package"]
}
}
}
원인 3: 패키지가 존재하지 않음
오타나 잘못된 패키지 이름을 지정하면 npx가 패키지를 찾지 못하고 종료합니다. MCP Logs에 npm ERR! 404 또는 Not Found 메시지가 나타납니다. 패키지 이름을 다시 확인하고, 가능하면 공식 저장소 README의 설치 명령을 그대로 복사해 사용하세요.
2. 인증 오류 (Unauthorized / 401 / API key invalid)
API 키가 필요한 서버에서 가장 흔히 나타나는 오류입니다.
체크리스트
| 확인 항목 | 방법 |
|---|---|
| 키 값이 env 블록에 있는가 | .cursor/mcp.json의 env 필드 확인 |
| 키 앞뒤에 공백·줄바꿈이 없는가 | 키를 재복사해 붙여넣기 |
| 키가 유효 기간 내인가 | 서비스 대시보드에서 만료일 확인 |
| 키에 필요한 권한이 있는가 | 서비스별 권한 설정 페이지 확인 |
수정 후에는 반드시 Cursor를 완전히 종료 후 재시작해야 변경이 반영됩니다.
3. MCP 서버 크래시 (exit code 1 / 프로세스 반복 종료)
서버가 시작 직후 또는 특정 요청 처리 중 종료되는 경우입니다.
원인 분석 순서
- MCP Logs에서
exit code직전 에러 메시지 복사 Error: Cannot find module→ 패키지 의존성 누락. 해당 패키지를 전역 설치하거나 서버 디렉토리에서npm install실행SyntaxError→ Node.js 버전 불일치 가능성.node --version으로 확인 후 필요시 업데이트EACCES→ 파일 권한 문제. 서버가 접근해야 할 파일·디렉토리의 권한 확인- 메모리 관련 오류 → 서버가 처리할 수 있는 데이터 크기를 초과했을 가능성
# 서버를 터미널에서 직접 실행해 오류 확인
npx -y my-mcp-package
터미널에서 직접 실행하면 Cursor 내부 로그보다 더 자세한 오류 메시지를 볼 수 있습니다.
4. 타임아웃 오류 (Request timed out)
서버는 실행 중이지만 응답이 늦어 타임아웃이 발생하는 경우입니다. 주로 외부 API를 호출하는 서버에서 나타납니다.
- 네트워크 상태 확인 (해당 API 서버에 직접 접속 테스트)
- 서버 측 API 레이트 리밋 초과 여부 확인
- 처리 대상 데이터가 지나치게 클 경우 분할 처리 고려
설정 파일 위치 정리
Cursor는 프로젝트 수준과 전역 수준 두 가지 설정을 지원합니다. 프로젝트 설정이 전역 설정보다 우선합니다.
| 구분 | 경로 | 적용 범위 |
|---|---|---|
| 프로젝트 설정 | [프로젝트 루트]/.cursor/mcp.json | 해당 프로젝트만 |
| 전역 설정 | ~/.cursor/mcp.json | 모든 프로젝트 |
두 파일이 모두 존재할 때 같은 이름의 서버가 있으면 프로젝트 설정 쪽이 적용됩니다. 예상과 다른 서버가 로드된다면 두 파일을 모두 확인하세요.
빠른 진단 체크리스트
오류 발생 시 순서대로 확인하면 대부분 해결됩니다.
[ ] 1. MCP Logs 열어 에러 메시지 확인
[ ] 2. .cursor/mcp.json JSON 문법 검증 (python3 -m json.tool)
[ ] 3. 설치 명령(npx/uvx) PATH 확인
[ ] 4. API 키가 env 블록에 올바르게 설정됐는지 확인
[ ] 5. Cursor 완전 종료 후 재시작
[ ] 6. 서버를 터미널에서 직접 실행해 상세 오류 확인
[ ] 7. Node.js / 런타임 버전 확인
[ ] 8. 공식 GitHub 이슈 트래커에서 동일 오류 검색
국내 MCP 서버 실전 예시
한국에서 자주 사용하는 MCP 서버들도 동일한 방법으로 오류를 진단할 수 있습니다. 예를 들어 코르독(KorDoc)은 한국 공문서(HWP·HWPX·PDF 등)를 Markdown으로 변환하는 서버로, 아래와 같이 설정합니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
HWP-MCP (한글 문서 MCP 서버)는 AI 어시스턴트가 한글(.hwp/.hwpx) 문서를 읽고 편집할 수 있게 해주는 서버입니다.
{
"mcpServers": {
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
}
}
}
한포지(HwpForge) 역시 HWPX 문서를 AI 에이전트가 다룰 수 있게 해주는 서버입니다.
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
이 서버들은 모두 API 키 없이 사용할 수 있으므로, 연결 오류가 발생한다면 대부분 JSON 문법 오류나 npx 경로 문제입니다. devtools 카테고리에서 더 많은 개발 도구 서버를 찾아보실 수 있습니다.
자주 묻는 질문
Cursor MCP Logs는 어디서 확인하나요?
Cursor 커맨드 팔레트(Cmd+Shift+P 또는 Ctrl+Shift+P)에서 MCP: Show Logs를 검색해 열 수 있습니다. 로그에는 서버 시작·종료·에러 메시지가 타임스탬프와 함께 표시되며, 서버별로 분리돼 있어 문제 서버를 빠르게 파악할 수 있습니다.
MCP 서버가 ‘Failed to connect’ 오류를 표시할 때 가장 먼저 확인해야 할 것은 무엇인가요?
.cursor/mcp.json의 JSON 문법 오류와 실행 명령 경로를 먼저 확인하세요. python3 -m json.tool로 문법을 검증하고, which npx로 실행 파일 경로를 점검합니다. 그다음 MCP Logs에서 구체적인 에러 메시지를 확인하면 원인이 빠르게 좁혀집니다.
인증 오류(Unauthorized / 401)가 반복될 때 어떻게 해결하나요?
API 키가 필요한 MCP 서버라면 설정 파일의 env 블록에 키 값이 올바르게 지정됐는지 확인하세요. 키 값에 따옴표 누락이나 공백이 섞이면 인증 실패가 발생합니다. 키를 재발급해 붙여넣은 뒤 Cursor를 완전히 재시작하면 대부분 해결됩니다.
MCP 서버가 자꾸 크래시(종료)될 때 원인은 무엇인가요?
런타임 의존성 누락이 가장 흔한 원인입니다. Node.js 버전이 맞지 않거나 필요한 패키지가 설치되지 않은 경우 서버가 시작 직후 종료됩니다. MCP Logs에서 exit code 또는 Error: Cannot find module 등의 메시지를 확인한 뒤, 해당 패키지를 설치하거나 Node.js 버전을 업데이트하세요.
설정 파일을 수정한 뒤에도 변경이 반영되지 않아요.
Cursor는 MCP 설정을 에디터 시작 시 한 번 읽습니다. 설정 파일을 수정했다면 Cursor를 완전히 종료 후 재시작해야 변경이 반영됩니다. 커맨드 팔레트에서 Developer: Reload Window를 실행해도 MCP 서버가 재초기화됩니다.
Cursor에서 여러 MCP 서버를 쓸 때 한 서버의 오류가 다른 서버에 영향을 주나요?
Cursor는 MCP 서버를 각각 독립 프로세스로 실행하므로, 한 서버가 크래시해도 다른 서버는 계속 동작합니다. 단, 설정 파일 자체가 JSON 파싱 오류이면 모든 서버가 로드되지 않으니 파일 전체 문법을 먼저 검증하세요.
다음 단계
오류를 해결했다면, 이제 MCP 서버를 더 안정적으로 운영해보세요. MCP 서버 전체 목록에서 필요한 도구를 찾아 추가하거나, 국내 개발자가 만든 서버들을 devtools 카테고리에서 탐색할 수 있습니다. 직접 만든 MCP 서버가 있다면 서버 등록을 통해 MCP모아에 등록해 더 많은 개발자와 공유해보세요.