​
MCP란?

Model Context Protocol(MCP)은 Cursor가 외부 도구랑 데이터 소스에 연결될 수 있도록 해줘.

​
왜 MCP를 써?

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

​
동작 방식

MCP 서버는 프로토콜을 통해 기능을 공개해서 Cursor를 외부 도구나 데이터 소스에 연결해. Cursor는 세 가지 전송 방식을 지원해:
Transport실행 환경배포사용자입력인증
stdio로컬Cursor가 관리단일 사용자셸 명령수동
SSE로컬/원격서버로 배포다중 사용자SSE 엔드포인트 URLOAuth
Streamable HTTP로컬/원격서버로 배포다중 사용자HTTP 엔드포인트 URLOAuth

​
프로토콜 지원

Cursor는 다음 MCP 프로토콜 기능을 지원해:
기능지원 여부설명
Tools지원됨AI 모델이 실행하는 함수
Prompts지원됨사용자용 템플릿 메시지와 워크플로우
Resources지원됨읽고 참조할 수 있는 구조화된 데이터 소스
Roots지원됨동작 범위를 정의하기 위한 URI 또는 파일 시스템 경계에 대한 서버 주도 조회
Elicitation지원됨사용자에게 추가 정보를 요청하는 서버 주도 요청

​
MCP 서버 설치

​
원클릭 설치

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

MCP 도구 살펴보기

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

Add to Cursor 버튼

“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 파일을 수정하지 않고도 동적으로 설정할 수 있는 Extension 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 도구를 쓰기 전에 승인을 요청해. 인자를 보려면 도구 이름 옆 화살표를 클릭해.

​
자동 실행

에이전트가 확인 없이 MCP 도구를 쓰도록 자동 실행을 켜줘. 터미널 명령처럼 동작해. Yolo 모드에 대해 더 알고 싶다면 여기를 확인해.

​
도구 응답

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, 브라우저 도구를 통합하는 방법을 보여주는 웹 개발 가이드를 확인해봐.

​
FAQ