cursor-mcp-json

Cursor MCP mcp.json 파일을 통해 서버를 연결하려면 올바른 위치에 서버 설정을 작성해야 합니다. 이 글은 Cursor 공식 문서를 기준으로 mcp.json 파일의 위치, 서버 항목 작성법, 연결 실패 시 점검 순서를 정리한 것이며, 세부 동작은 공식 문서 업데이트에 따라 달라질 수 있습니다. (2026년 9월 기준)

mcp.json은 어디에 두나?

한 줄 답: 프로젝트 폴더의 .cursor/mcp.json 또는 홈 디렉터리의 ~/.cursor/mcp.json에 두며, 두 파일이 모두 있으면 병합되고 이름이 겹치면 프로젝트 설정이 우선합니다.

공식 문서는 mcp.json을 만들 수 있는 위치를 두 곳으로 안내합니다. 첫째는 프로젝트 전용 설정으로, 프로젝트 폴더 안의 .cursor/mcp.json입니다. 팀원과 같은 도구를 공유할 목적이면 이 파일을 git에 커밋하라고 안내합니다. 둘째는 전역 설정으로, 홈 디렉터리의 ~/.cursor/mcp.json입니다. 모든 프로젝트에서 공통으로 쓸 서버는 여기에 둡니다.

두 파일이 모두 존재하면 병합되며, 같은 서버 이름이 양쪽에 있으면 프로젝트 수준 설정이 우선 적용된다고 공식 문서가 명시합니다. 파일을 만들거나 고친 뒤에는 저장하고 Cursor를 재시작해야 반영됩니다.

서버 항목은 어떻게 쓰나?

한 줄 답: mcpServers 객체 아래 서버 이름을 키로 두고, 로컬 실행은 command/args/env(+envFile), 원격 연결은 url/headers 필드로 작성합니다.

최상위 mcpServers 객체 안에 원하는 서버 이름을 키로 추가합니다. 로컬에서 실행하는 stdio 서버는 공식 문서에 나온 다음 형태를 그대로 사용합니다.

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

공식 레퍼런스 표는 stdio 서버의 필드로 command(필수, 시스템 PATH에 있거나 전체 경로여야 함), args, env, envFile을 설명합니다. envFile은 stdio 서버에만 쓸 수 있고, 원격 서버는 지원하지 않는다고 명시되어 있습니다.

URL로 제공되는 원격(HTTP/SSE) 서버는 url 필드로 연결하고, 인증이 필요하면 headers를 추가합니다.

{
  "mcpServers": {
    "my-service": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

값에는 구성 보간(config interpolation)을 사용할 수 있습니다. ${env:NAME}, ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename}, ${pathSeparator}를 command, args, env, url, headers 필드에 넣어 하드코딩 대신 참조할 수 있습니다. 설정을 저장한 뒤에는 Cursor를 재시작해야 새 서버가 반영됩니다.

연결 실패 시 무엇을 점검하나?

한 줄 답: JSON 문법과 command의 PATH 등록 여부를 먼저 보고, Output 패널의 MCP Logs를 확인한 뒤 서버 토글이나 재추가로 점검합니다.

mcp.json의 JSON 문법(콤마, 중괄호 등)이 올바른지 먼저 확인합니다. stdio 서버라면 command에 지정한 실행 파일이 시스템 PATH에 있는지, 없다면 전체 경로로 지정했는지 확인합니다. 서버가 셸 프로필에 설정된 환경 변수에 의존한다면 그 변수가 Cursor에도 보이는지 확인해야 하며, 공식 문서는 셸 프로필을 바꾼 뒤에는 Cursor를 재시작해야 한다고 안내합니다.

Output 패널(Mac: Cmd+Shift+U, Windows/Linux: Ctrl+Shift+U)을 열고 드롭다운에서 MCP Logs를 선택하면 서버 초기화 오류, 인증 오류, 서버 크래시 메시지를 확인할 수 있습니다. Customize의 MCPs 탭에서 해당 서버가 꺼져 있지 않은지 토글도 함께 확인합니다.

위 방법으로 해결되지 않으면 Customize의 MCPs 탭에서 서버를 제거한 뒤 다시 추가하라고 공식 문서가 안내합니다. 서버 하나가 실패해도 다른 MCP 서버는 계속 정상 동작한다고 공식 문서는 설명합니다.

FAQ

Q1. 여러 서버를 동시에 등록할 수 있습니까?

A1. 네, mcpServers 객체 안에 서버 이름을 여러 개 나열하면 됩니다.

Q2. 현재 프로젝트 경로를 변수로 참조할 수 있습니까?

A2. 네, ${workspaceFolder} 보간 변수로 .cursor/mcp.json이 있는 프로젝트 루트를 참조할 수 있습니다.

Q3. 환경 변수를 파일로 몰아서 지정할 수 있습니까?

A3. 네, stdio 서버에서는 envFile 필드로 .env 같은 파일을 지정할 수 있습니다. 다만 원격 서버는 envFile을 지원하지 않습니다.

Q4. 서버를 삭제하지 않고 잠시 끌 수 있습니까?

A4. 네, Customize의 MCPs 탭에서 토글로 활성/비활성을 전환할 수 있습니다.

출처 (Sources)