​
MCP란?

Model Context Protocol(MCP)은 Cursor가 외부 도구와 데이터 소스에 연결하도록 해준다.

​
왜 MCP를 써야 할까?

MCP는 Cursor를 외부 시스템과 데이터에 연결해. 프로젝트 구조를 매번 설명하는 대신, 네 도구랑 바로 통합하면 돼. stdout에 출력하거나 HTTP 엔드포인트를 제공할 수만 있다면 어떤 언어로든 MCP 서버를 만들 수 있어 — Python, JavaScript, Go 등.

​
작동 방식

MCP 서버는 프로토콜을 통해 기능을 제공해서 Cursor를 외부 도구나 데이터 소스와 연결해. Cursor는 세 가지 전송 방식을 지원해:
TransportExecution environmentDeploymentUsersInputAuth
stdioLocalCursor managesSingle userShell commandManual
SSELocal/RemoteDeploy as serverMultiple usersURL to an SSE endpointOAuth
Streamable HTTPLocal/RemoteDeploy as serverMultiple usersURL to an HTTP endpointOAuth

​
프로토콜 지원

Cursor는 다음 MCP 프로토콜 기능을 지원해:
FeatureSupportDescription
ToolsSupportedAI 모델이 실행할 함수
PromptsSupported사용자용 템플릿 메시지와 워크플로
ResourcesSupported읽고 참조할 수 있는 구조화된 데이터 소스
RootsSupported작업을 수행할 URI 또는 파일 시스템 경계를 서버가 조회
ElicitationSupported사용자에게 추가 정보를 요청하는 서버 주도 요청

​
MCP 서버 설치

​
원클릭 설치

컬렉션에서 MCP 서버를 설치하고 OAuth로 인증해.

Browse MCP Tools

사용 가능한 MCP 서버 살펴보기

Add to Cursor Button

“Add to Cursor” 버튼 만들기

​
mcp.json 사용하기

JSON 파일로 커스텀 MCP 서버를 설정해: 
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

​
STDIO 서버 구성

STDIO 서버(로컬 커맨드라인 서버)의 경우, mcp.json에서 다음 필드를 설정해:
FieldRequiredDescriptionExamples
typeYes서버 연결 유형"stdio"
commandYes서버 실행 파일을 시작할 명령. 시스템 PATH에 있거나 전체 경로를 포함해야 해."npx", "node", "python", "docker"
argsNo명령에 전달되는 인수 배열["server.py", "--port", "3000"]
envNo서버용 환경 변수{"API_KEY": "${input:api-key}"}
envFileNo추가 변수를 로드할 환경 파일 경로".env", "${workspaceFolder}/.env"

​
Extension API 사용하기

코드로 MCP 서버를 등록할 수 있도록, Cursor는 mcp.json 파일을 수정하지 않고도 동적으로 설정을 구성할 수 있는 확장 API를 제공해. 엔터프라이즈 환경이나 자동화된 설정 워크플로에 특히 유용해.

MCP Extension API Reference

vscode.cursor.mcp.registerServer()로 코드에서 MCP 서버를 등록하는 방법 알아보기

​
구성 위치

프로젝트 구성

프로젝트 전용 도구는 프로젝트 루트에 .cursor/mcp.json 만들어줘.

전역 구성

어디서나 쓰는 도구는 홈 디렉터리에 ~/.cursor/mcp.json 만들어줘.

​
구성 보간

mcp.json 값에서 변수를 써. Cursor는 다음 필드의 변수를 해석해: command, args, env, url, headers. 지원되는 문법:
  • ${env:NAME} 환경 변수
  • ${userHome} 홈 폴더 경로
  • ${workspaceFolder} 프로젝트 루트(“.cursor/mcp.json”이 들어 있는 폴더)
  • ${workspaceFolderBasename} 프로젝트 루트 이름
  • ${pathSeparator} 및 ${/} OS 경로 구분자
예제 
{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

​
인증

MCP 서버는 인증에 환경 변수를 사용해. API 키와 토큰은 config로 전달해. Cursor는 OAuth가 필요한 서버를 지원해.

​
채팅에서 MCP 사용하기

Composer Agent는 상황에 맞으면 Available Tools에 표시된 MCP 도구를 자동으로 써. 특정 도구를 이름으로 지목하거나, 필요한 걸 설명해 줘. 설정에서 도구를 켜거나 끌 수 있어.

​
도구 토글하기

채팅 인터페이스에서 MCP 도구를 바로 켜거나 꺼. 도구 목록에서 도구 이름을 클릭하면 토글돼. 비활성화된 도구는 컨텍스트에 로드되지 않고 Agent에서도 사용할 수 없어.

​
도구 승인

에이전트는 기본적으로 MCP 도구를 쓰기 전에 승인을 먼저 받아. 인자를 보려면 도구 이름 옆 화살표를 클릭해.

​
자동 실행

Agent가 묻지 않고 MCP 도구를 쓰도록 자동 실행을 켜줘. 터미널 명령처럼 동작해. 자동 실행 설정은 여기에서 더 알아봐.

​
도구 응답

Cursor는 인수와 응답을 펼쳐볼 수 있는 보기와 함께, 채팅에 응답을 표시해:

​
컨텍스트로서의 이미지

MCP 서버는 스크린샷, 다이어그램 등 이미지를 반환할 수 있어. base64로 인코딩한 문자열로 반환해: 
const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w...";
// ^ 가독성을 위해 전체 base64는 잘렸어

server.tool("generate_image", async (params) => {
  return {
    content: [
      {
        type: "image",
        data: RED_CIRCLE_BASE64,
        mimeType: "image/jpeg",
      },
    ],
  };
});
구현 방식은 이 예시 서버를 참고해. Cursor는 반환된 이미지를 채팅에 첨부해. 모델이 이미지를 지원하면 해당 이미지를 분석해.

​
보안 고려사항

MCP 서버를 설치할 때는 다음 보안 모범 사례를 고려해봐:
  • 소스 검증: 신뢰할 수 있는 개발자와 저장소에서 제공하는 MCP 서버만 설치하기
  • 권한 검토: 서버가 어떤 데이터와 API에 접근하는지 확인하기
  • API 키 제한: 최소 권한으로 제한된 API 키 사용하기
  • 코드 검토: 중요한 통합의 경우 서버의 소스 코드를 리뷰하기
MCP 서버는 외부 서비스에 접근하고 네 대신 코드를 실행할 수 있다는 점을 기억해. 설치 전에 서버가 무엇을 하는지 항상 정확히 이해해둬.

​
실제 사례

MCP가 실제로 어떻게 쓰이는지 보려면, 개발 워크플로우에 Linear, Figma, 그리고 브라우저 도구를 통합하는 방법을 보여주는 웹 개발 가이드를 확인해봐.

​
자주 묻는 질문

MCP 서버는 Cursor를 Google Drive, Notion 같은 외부 도구와 서비스에 연결해서 문서와 요구사항을 네 코딩 워크플로에 바로 가져와.
MCP 로그를 보려면: 1. Cursor에서 Output 패널 열기 (Ctrl+Shift+U) 2. 드롭다운에서 “MCP Logs” 선택 3. 연결 오류, 인증 문제, 서버 크래시 확인 로그에는 서버 초기화, 도구 호출, 오류 메시지가 표시돼.
물론! 제거하지 않고 서버를 켜거나 끌 수 있어: 1. 설정 열기 (Ctrl+Shift+J) 2. Features → Model Context Protocol로 이동 3. 원하는 서버 옆 토글을 클릭해서 활성화/비활성화 비활성화한 서버는 로드되지 않고 채팅에 나타나지 않아. 문제 해결이나 도구가 너무 많을 때 정리하는 데 유용해.
MCP 서버가 실패하면: - Cursor가 채팅에 오류 메시지를 보여줘 - 도구 호출은 실패로 표시돼 - 작업을 다시 시도하거나 로그에서 상세 정보를 확인할 수 있어 - 다른 MCP 서버는 정상적으로 계속 동작해 Cursor는 한 서버의 실패가 다른 서버에 영향 주지 않도록 격리해.
npm 기반 서버의 경우: 1. 설정에서 서버 제거 2. npm 캐시 비우기: npm cache clean --force 3. 최신 버전을 받으려면 서버 다시 추가 커스텀 서버는 로컬 파일을 업데이트하고 Cursor를 재시작해.
가능해, 대신 보안 모범 사례를 따라야 해: - 시크릿은 환경 변수로 관리하고 하드코딩하지 마 - 민감한 서버는 stdio 트랜스포트로 로컬에서 실행해 - API 키 권한은 필요한 최소로 제한해 - 민감한 시스템에 연결하기 전에 서버 코드를 검토해 - 격리된 환경에서 서버를 실행하는 것도 고려해