Cursor에서 MCP 서버 문제 해결

Cursor MCP settings panel showing a server that failed to connect

MCP 서버는 외부 도구로 Cursor를 확장하지만, 자체 종속성을 가진 독립 프로세스이며, 문제가 생기면 증상이 혼란스러울 수 있습니다: 빨간색으로 표시되는 서버, 갱신되지 않는 도구 목록, 또는 아무것도 하지 않는 것처럼 보이는 연결 해제 버튼. 이 가이드는 빠른 분류 체크리스트부터 각 흔한 실패 모드에 대한 구체적 수정까지 Cursor의 MCP 문제를 체계적으로 진단하는 방법을 제공하고, IDE 외부에서 모든 서버를 검증하여 문제가 서버에 있는지 Cursor의 연결에 있는지 판단할 수 있게 해줍니다.

빠른 분류 체크리스트

MCP 서버가 오작동할 때 이 표를 위에서 아래로 진행하세요. 대부분의 문제는 처음 세 행에서 해결됩니다.

증상	먼저 확인할 것	일반적인 수정
서버가 빨간색으로 표시되거나 시작 실패	터미널에서 서버 명령을 수동으로 실행	명령 경로, 누락된 런타임, 또는 환경 변수 수정
도구 누락 또는 오래됨	재시작 없이 mcp.json을 편집했는가?	Cursor 재시작 또는 창 새로고침
연결 해제 버튼이 아무것도 하지 않음	프로세스가 실제로 죽었는가?	프로세스를 수동으로 종료한 후 다시 연결
서버 오류가 나고 재시도 안 함	Cursor는 일부 실패 후 자동 재시도하지 않음	서버를 껐다 켜거나 재시작
요청이 멈추다 타임아웃	서버 시작 또는 도구 런타임이 너무 느림	종속성 사전 준비, 타임아웃 상향
인증 오류	토큰 만료 또는 환경 변수 누락	토큰 갱신, 환경 수정

서버가 시작되지 않음

가장 흔한 MCP 실패는 가장 단순한 것입니다: Cursor가 서버를 실행하는 데 사용하는 명령이 실제로 작동하지 않는 것입니다. Cursor는 mcp.json에 있는 명령을, 제공한 환경으로 정확히 실행하며, 그것이 실패하면 서버는 나타나지 않습니다.

잘못된 명령 경로

Cursor가 실행할 방식 그대로 명령을 확인하세요. mcp.json에 command": "npx"라고 되어 있지만 Cursor 프로세스 내부의 PATH에 npx가 포함되어 있지 않으면 실행이 실패합니다. Windows에서는 GUI 애플리케이션이 터미널과 다른 PATH를 상속하므로 특히 흔합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

Windows에서는 실행 파일의 절대 경로를 사용하는 것이 신뢰할 수 있는 수정입니다. macOS와 Linux에서는 기본 명령이 발견되지 않으면 which npx가 절대 경로를 알려줍니다.

npx 또는 uvx 누락

많은 MCP 서버는 npm 또는 Python 패키지로 제공되며 npx 또는 uvx를 통해 실행됩니다. 런타임이 설치되어 있지 않으면 서버가 시작될 수 없습니다:

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

uvx가 누락되어 있으면 설치하고 터미널과 Cursor를 재시작하여 업데이트된 PATH가 반영되도록 하세요.

잘못된 환경 변수

API 키가 필요한 서버는 환경이 잘못되면 시작 후 즉시 종료되거나, 시작하지만 모든 도구 호출에서 오류를 반환하는 경우가 많습니다. 서버의 문서에서 정확한 변수 이름을 확인하고, Cursor는 env 블록에 나열한 것만 전달한다는 점을 기억하세요:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

mcp.json 편집 후 도구가 다시 로드되지 않음

mcp.json을 편집하고 저장하고 도구 목록을 열어도 새 도구가 없습니다. MCP 구성은 서버 프로세스가 시작될 때 읽히므로, 편집이 모든 상황에서 핫 리로드되지는 않습니다.

파일을 저장하고 유효한 JSON인지 확인합니다. 후행 쉼표는 전체 파일을 파싱 불가능하게 만들어 모든 서버가 실패할 수 있습니다.
Cursor를 완전히 재시작하거나, 버전이 명령 팔레트에서 새로고침 옵션을 제공하면 창을 새로고침합니다.
MCP 설정 패널을 열고 서버가 연결됨으로 표시되는지 확인합니다.
새 채팅을 시작합니다. 기존 대화는 오래된 도구 목록을 캐시했을 수 있으므로 새 도구는 새 세션에서만 나타납니다.

새로고침보다 재시작

MCP 패널에서 서버를 껐다 켜도 변경 사항이 반영되지 않으면 전체 창 새로고침이나 Cursor 재시작을 하세요. mcp.json은 연결 시점에 읽히며, 오래된 프로세스는 파일이 지금 무엇을 말하든 원래 도구 목록을 계속 제공합니다.

연결 및 재시도 문제

연결 해제 버튼이 아무것도 하지 않음

연결 해제 작업은 연결의 Cursor 클라이언트 측을 중단하지만, stdio 서버에서는 실제 자식 프로세스가 깨끗하게 종료되지 않으면 살아남을 수 있습니다. 그 결과 절반 살아 있는 것처럼 보이고 깨끗한 재연결을 거부하는 서버가 됩니다. 버튼이 무시되는 것처럼 보일 때:

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

프로세스가 사라진 후 MCP 패널에서 다시 연결하세요. 다음 연결은 현재 구성으로 새 프로세스를 시작합니다.

서버 오류 후 재시도 없음

서버가 시작 중 또는 초기화 중 오류를 반환하면 Cursor는 일반적으로 백그라운드에서 계속 재시도하지 않습니다. 서버는 개입할 때까지 실패 상태로 남습니다. 강제 정도가 증가하는 수동 재시작 옵션:

MCP 설정 패널에서 서버를 껐다 켭니다.
모든 MCP 서버가 다시 연결되도록 Cursor 창을 새로고침합니다.
Cursor를 완전히 종료하고 재시작합니다.
프로세스가 멈춰 있으면 위에 표시된 대로 종료한 후 다시 연결합니다.

느린 서버의 타임아웃

첫 실행 시 종속성을 다운로드하는 서버나 느린 외부 API를 호출하는 도구는 기본 타임아웃을 초과하여 깨진 서버처럼 보이는 실패를 보고할 수 있습니다. 전형적인 경우는 npx 기반 서버의 첫 호출로, npm이 무언가 시작되기 전에 패키지를 가져오는 상황입니다:

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

호스트 수준 타임아웃의 경우, Cursor를 포함한 많은 MCP 호스트가 관례적인 타임아웃 환경 변수를 존중합니다. Cursor를 실행하기 전에 설정하면 느린 서버에 더 많은 여유를 줍니다:

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

서버가 여전히 너무 느리면 다르게 호스팅하세요: 영구 로컬 프로세스로 실행하고 세션마다 실행하는 대신 SSE나 HTTP로 연결하세요.

전송 유형: stdio vs SSE/HTTP

Cursor는 두 가지 MCP 전송 스타일을 지원하며, 여러 문제 해결 단계가 이들 간에 다릅니다.

측면	stdio	SSE / HTTP
실행 방식	Cursor가 프로세스를 실행	서버가 별도로 실행, Cursor가 URL에 연결
구성 키	`command`, `args`, `env`	`url` (및 지원되는 경우 헤더)
흔한 실패	잘못된 명령 경로, 누락된 런타임	잘못된 URL, 인증 헤더, CORS 또는 네트워크 문제
재시작 동작	토글이 프로세스를 다시 연결	재연결이 원격 엔드포인트를 호출
디버깅	명령을 수동으로 실행	엔드포인트를 curl, 서버 로그 확인

{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

SSE 및 HTTP 서버의 경우 Cursor를 건드리기 전에 엔드포인트에 도달할 수 있는지 확인하세요:

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

401 또는 403은 전송이 정상이고 인증이 문제임을 의미합니다. 타임아웃 또는 연결 거부는 서버가 다운되었거나 URL이 잘못되었음을 의미합니다.

환경 변수와 시크릿

프로젝트 vs 전역 mcp.json

Cursor는 두 곳에서 MCP 구성을 읽습니다:

전역: ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json). 모든 프로젝트에 적용됩니다. 개인 서버를 여기에 두세요: GitHub 토큰, 데이터베이스 브라우저, 스크래핑 도구.
프로젝트: 리포지토리 내부의 .cursor/mcp.json. 해당 프로젝트에만 적용되며 커밋 시 팀원과 공유됩니다. 프로젝트별 서버를 여기에 두세요: 이 리포지토리 데이터베이스용 스키마 MCP, 이 코드베이스가 사용하는 디자인 도구 통합.

서버가 두 곳에 모두 정의되어 있으면 프로젝트 구성이 해당 프로젝트를 지배할 것으로 예상하세요. 도구가 중복되거나 사라지면 두 파일에서 같은 이름의 항목을 확인하세요.

시크릿을 안전하게 전달

Cursor는 env 블록의 ${VAR_NAME} 자리 표시자를 환경에서 확장하므로 시크릿이 mcp.json 외부에 있을 수 있습니다:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}

# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"

시크릿을 리포지토리에 커밋하지 마세요

프로젝트 수준 .cursor/mcp.json은 리포지토리의 일반 파일입니다. 리터럴 API 키가 포함되어 있으면 리포지토리를 클론하는 모든 사람과 모든 agent가 키를 얻게 됩니다. 민감한 모든 항목에는 ${VAR} 확장을 사용하고, 로컬 값을 포함해야 한다면 프로젝트 mcp.json을 .gitignore에 추가하세요.

MCP 로그 읽기

증상이 불분명할 때 로그가 보통 실제 문제를 알려줍니다. Cursor는 출력 인프라를 통해 MCP 활동을 표시합니다:

명령 팔레트를 열고 출력 패널을 표시하는 명령을 실행하거나 View 메뉴를 사용합니다.
출력 패널의 채널 드롭다운에서 MCP 또는 Cursor MCP 로그 채널을 선택합니다.
실패하는 작업을 트리거한 다음 최신 항목을 읽습니다. spawn 오류, 0이 아닌 종료 코드, 서버의 stderr에서 온 스택 추적을 찾으세요.

일반적인 로그 줄과 그 의미:

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

서버 측 stderr가 이 로그로 전달되므로, 서버 자체의 Python 트레이스백이나 누락된 종속성 예외가 보통 여기에 그대로 나타납니다.

서버를 독립 실행으로 검증

문제가 Cursor의 것인지 서버의 것인지 증명하는 가장 빠른 방법은 Cursor 없이 서버를 실행하는 것입니다.

명령을 수동으로 실행

mcp.json에서 command와 args를 복사하여 일반 터미널에서 실행하세요:

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

정상적인 stdio MCP 서버는 시작하고 stdin에서 JSON-RPC 입력을 조용히 기다립니다. 대신 명령을 찾을 수 없다는 오류, 충돌, 또는 패키지 설치 실패가 보이면 문제를 찾은 것이고 Cursor는 무죄입니다. 몇 글자를 입력하고 Enter를 누르세요; 순수한 프로토콜 오류 응답은 실제로 좋은 신호인데, 프로세스가 JSON-RPC를 말하고 있다는 것을 증명하기 때문입니다.

MCP Inspector 사용

공식 MCP inspector는 서버에 연결하고, 도구를 나열하고, 대화식으로 호출할 수 있게 해줍니다:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

이것은 로컬 웹 인터페이스를 열어 서버를 초기화하고, 도구를 나열하고, 손으로 작성한 인수로 하나를 호출할 수 있게 합니다. 도구가 inspector에서는 작동하지만 Cursor에서는 작동하지 않으면, 차이는 보통 환경입니다: 터미널에는 있지만 Cursor 프로세스에는 없는 변수, 또는 다른 작업 디렉터리. inspector에서도 도구가 실패하면 먼저 서버를 수정하세요; Cursor에서 변경하는 것은 아무 도움이 되지 않습니다.

최소 작동 mcp.json

구성이 더 이상 시작되지 않는 것으로 표류했을 때 참조로 사용하세요. 하나의 stdio 서버와 하나의 원격 서버를 환경 확장과 함께 보여줍니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

서버에 맞게 조정하기 위한 체크리스트:

패키지 이름과 인수를 서버 문서의 것으로 교체합니다.
Windows에서는 기본 명령이 발견되지 않으면 절대 실행 파일 경로를 사용합니다.
시크릿은 ${VAR} 자리 표시자로 유지하고 실제 값은 셸 프로필에 설정합니다.
JSON을 검증한 다음 Cursor를 재시작하고 채팅을 열기 전에 서버가 연결됨으로 표시되는지 확인합니다.

하나의 잘못된 항목이 전체 파일을 깨뜨릴 수 있습니다

mcp.json은 단일 JSON 문서로 파싱됩니다. 후행 쉼표 하나나 따옴표 없는 값 하나가 전체 파일을 무효로 만들고, 그 안의 모든 서버가 함께 시작에 실패할 수 있습니다, 잘 작동하던 서버까지도 포함해서요. 여러 서버가 동시에 깨지면 각 서버를 의심하기 전에 파일 구문을 의심하세요.

빠른 참조

목표	이렇게 하세요
시작 후 서버가 빨간색	명령을 수동으로 실행; 경로, 런타임, 또는 env 수정
새 도구가 나타나지 않음	창을 새로고침한 다음 새 채팅 시작
연결 해제가 응답 없음	자식 프로세스를 종료한 후 다시 연결
반복 실패, 재시도 없음	서버를 껐다 켜거나 Cursor 재시작
첫 실행 타임아웃	패키지를 사전 준비, 타임아웃 환경 변수 상향
서버를 의심, Cursor가 아니라	수동 실행 또는 MCP inspector로 검증
Cursor를 의심, 서버가 아니라	터미널과 env를 비교하고 MCP 로그 채널 읽기

빠른 분류 체크리스트​

서버가 시작되지 않음​

잘못된 명령 경로​

npx 또는 uvx 누락​

잘못된 환경 변수​

mcp.json 편집 후 도구가 다시 로드되지 않음​

연결 및 재시도 문제​

연결 해제 버튼이 아무것도 하지 않음​

서버 오류 후 재시도 없음​

느린 서버의 타임아웃​

전송 유형: stdio vs SSE/HTTP​

환경 변수와 시크릿​

프로젝트 vs 전역 mcp.json​

시크릿을 안전하게 전달​

MCP 로그 읽기​

서버를 독립 실행으로 검증​

명령을 수동으로 실행​

MCP Inspector 사용​

최소 작동 mcp.json​

빠른 참조​