Cursor에 MCP 서버 추가하기: mcp.json 위치(전역·프로젝트), 원격 url과 로컬 command 형태, OAuth 로그인, 원클릭 설치 링크.

요약: Cursor는 mcp.json에서 MCP 서버를 읽습니다. 전역으로는 ~/.cursor/mcp.json, 프로젝트별로는 .cursor/mcp.json입니다. 원격 서버는 url 항목이고, 로컬 서버는 args가 딸린 command입니다. 파일을 저장하고 Cursor Settings → Tools & MCP를 열어, 서버에 Needs login이 표시되면 로그인하세요. 그러면 Agent가 도구를 사용할 수 있습니다. 서버는 원클릭 설치 링크로도 공유할 수 있으며, UnifAPI용 링크는 아래에 있습니다.

Cursor의 MCP 지원은 파일 기반이며, 이는 좋은 소식입니다. OAuth 로그인 말고는 클릭해서 넘어갈 것이 없고, 설정은 커밋할 수 있으며, 모든 서버에 같은 JSON 형태가 통합니다. 이 가이드는 UnifAPI MCP 서버(https://mcp.unifapi.com, X, Instagram, TikTok, YouTube, Reddit, LinkedIn, Threads와 SEO 스택의 실시간 공개 데이터)를 예시로 사용합니다.

mcp.json의 위치

파일	범위	용도
`~/.cursor/mcp.json`	이 머신의 모든 프로젝트, 이 사용자	어디서나 쓰고 싶은 서버(데이터 서버, 브라우저, 문서 서버)
`.cursor/mcp.json`	프로젝트 하나, 저장소와 함께 커밋	코드베이스에 속한 서버. 팀원은 클론할 때 함께 받음

두 파일은 같은 형태를 공유하며, Cursor가 둘을 병합합니다. 같은 이름이 양쪽에 있으면 프로젝트 항목이 우선합니다.

원격 서버: url 형태

파일을 만들거나 편집해 mcpServers 아래에 서버를 추가하세요.

{
  "mcpServers": {
    "unifapi": {
      "url": "https://mcp.unifapi.com"
    }
  }
}

저장합니다. Cursor Settings → Tools & MCP(이전 빌드에서는 MCP & Integrations)를 엽니다. 서버가 상태 점과 함께 나타납니다. UnifAPI처럼 OAuth로 보호된 서버에는 Needs login이 표시됩니다. 클릭하고, 브라우저 창에서 UnifAPI 계정으로 로그인하거나 새로 만든 뒤, 읽기 전용 스코프를 승인하세요. 점이 녹색으로 바뀌고 서버 아래에 도구 목록이 펼쳐집니다: list_operations, get_operation, call_api.

Cursor는 UnifAPI가 사용하는 OAuth 2.0 동적 클라이언트 등록을 지원하므로 클라이언트 ID가 필요하지 않습니다. 고정 클라이언트 ID를 발급하거나 허용 목록에 등록된 리디렉션 URL을 요구하는 제공자의 경우, Cursor는 url 옆에 CLIENT_ID, 선택적인 CLIENT_SECRET, scopes를 담은 auth 블록을 받습니다. UnifAPI에는 필요하지 않습니다.

OAuth 대신 정적 토큰을 사용하는 원격 서버는 headers를 받으며, 값은 환경 변수에서 가져올 수 있습니다.

{
  "mcpServers": {
    "example": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${env:EXAMPLE_TOKEN}"
      }
    }
  }
}

UnifAPI는 이 방식으로 워크스페이스 API 키를 받기도 하지만, 권장 경로는 OAuth입니다. 파일에 비밀 정보가 남지 않고, 토큰은 읽기 전용입니다.

로컬 서버: command 형태

내 컴퓨터에서 실행되는 서버는 Cursor가 시작하는 명령입니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
      "env": {
        "NODE_OPTIONS": "--max-old-space-size=512"
      }
    }
  }
}

${workspaceFolder}, ${userHome}, ${env:NAME}은 치환되므로, 커밋된 .cursor/mcp.json도 머신에 독립적으로 유지할 수 있습니다. command와 url은 배타적이며, 둘을 모두 가진 항목은 무시됩니다.

원클릭 설치 링크

Cursor는 딥링크로 서버를 설치할 수 있으며, 벤더가 문서에 "Add to Cursor" 버튼을 두는 방식이 이것입니다. 링크에는 서버 이름과, 직접 작성할 때와 같은 JSON이 base64로 인코딩되어 담깁니다.

cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_CONFIG

UnifAPI의 경우 config는 {"url":"https://mcp.unifapi.com"}의 base64입니다.

cursor://anysphere.cursor-deeplink/mcp/install?name=unifapi&config=eyJ1cmwiOiJodHRwczovL21jcC51bmlmYXBpLmNvbSJ9

브라우저에서 열면 서버가 Cursor로 전달되고, Cursor는 전역 mcp.json에 기록하기 전에 확인을 요청합니다. 직접 만들려면 echo -n '{"url":"https://…"}' | base64를 실행하고 두 매개변수를 바꾸세요. 링크는 온보딩에 편리하지만, 팀에는 여전히 커밋된 .cursor/mcp.json이 올바른 선택입니다.

도구 사용하기

MCP 도구는 Agent(기본 채팅 모드)가 사용하며, 인라인 편집이나 Tab에서는 사용하지 않습니다. 서버가 답할 수 있는 것을 요청하고 도구 호출이 나오는지 지켜보세요.

unifapi MCP 서버를 사용해 TikTok에서 사용할 수 있는 작업을 나열하고, 크리에이터의 최근 동영상을 반환하는 작업이 어느 것인지 알려줘.

Cursor는 MCP 설정에서 해당 서버의 자동 실행을 켜지 않으면 도구를 실행하기 전에 확인을 요청합니다. UnifAPI처럼 읽기 전용인 서버라면 자동 실행이 합리적입니다. 호출이 소비할 수 있는 것은 워크스페이스 크레딧뿐이고, get_operation이 call_api 실행 전에 record당 가격을 보여줍니다.

Cursor는 모델에 한 번에 제한된 수의 도구만 전달하고(활성화된 모든 서버를 합쳐 약 40개) 나머지는 비활성화하므로, 도구 표면이 작은 서버를 선호하세요. UnifAPI의 카탈로그가 세 가지 도구 뒤에 있는 것은 의도적입니다. 큰 카탈로그를 엔드포인트마다 도구 하나로 노출하면 대부분이 비활성화될 것입니다.

UnifAPI에서의 첫 작업

전체 루프를 거치는, 범위가 제한된 프롬프트:

unifapi MCP 도구로: 최근 7일 동안 "Cursor MCP"를 언급한 Reddit 스레드를 찾아 점수 기준 상위 20개를 가져오고, 반복되는 설정 문제를 각각 예시 스레드 하나와 함께 요약해 줘. call_api 전에 list_operations와 get_operation을 호출해.

과금은 공개 데이터 record당 워크스페이스 크레딧으로 이루어집니다(개당 $0.001, 대부분의 record는 1크레딧, 최소 크레딧이 더 높은 작업은 카탈로그에 게시). 모델 토큰은 Cursor 플랜에서 소비됩니다. 새 UnifAPI 워크스페이스는 첫 충전 전까지 크레딧이 없고 첫 충전에는 일회성 보너스가 따라오므로, 첫 call_api 전에 한 번 충전하세요.

엔드포인트가 아니라 작업에서 시작하고 싶다면, 플랫폼 에이전트(Reddit, X, LinkedIn, TikTok, YouTube, Instagram, Threads)와 SEO 에이전트가 각각 준비된 프롬프트와 필요한 작업을 담고 있습니다.

문제 해결

증상	해야 할 일
`mcp.json` 저장 후 서버가 목록에 없음	JSON 검증(후행 쉼표 없음). Tools & MCP에서 서버를 끄고 다시 켜거나 창 다시 로드
Needs login이 사라지지 않음	팝업이 차단되었거나 OAuth 창에서 다른 계정으로 로그인함. 상태를 다시 클릭하거나 서버를 제거 후 다시 추가
도구가 나열되지만 회색으로 비활성화됨	Cursor의 활성 도구 한도를 초과함. 사용하지 않는 서버를 비활성화
Agent가 도구를 호출하지 않고 답함	프롬프트에서 서버 이름을 한 번 언급("unifapi MCP 서버를 사용해"). 한 번 성공하면 스스로 도구를 찾음
`call_api`가 `insufficient_credits`를 반환	워크스페이스에 아직 크레딧이 없음. UnifAPI 콘솔에서 한 번 충전한 뒤 재실행
팀원에게 프로젝트 서버가 보이지 않음	`.cursor/mcp.json`이 커밋되지 않았거나, 팀원의 Cursor가 아직 워크스페이스를 신뢰하지 않음

확인한 출처

2026년 10월 14일에 Cursor의 MCP 문서(설정 형태, OAuth, 치환)와 설치 링크 레퍼런스에 맞춰 작성했습니다. 설정 레이블은 Cursor 릴리스마다 바뀌지만, 파일 형식은 안정적으로 유지되어 왔습니다.

다음에 읽을 글

MCP 설정 - 모든 클라이언트의 호스팅 커넥터 안내.

Claude에 MCP 서버 추가하는 방법 - 커넥터, claude_desktop_config.json, claude mcp add.

Codex MCP 설정 - codex mcp add와 config.toml.

에이전트 컨텍스트: 규칙, 스킬, MCP - 규칙 파일과 스킬 옆에서 MCP가 차지하는 자리.