모델 컨텍스트 프로토콜(MCP)

MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)을 사용하면 Cursor를 외부 도구 및 데이터 소스에 연결할 수 있습니다. 사용자 지정하기 페이지에서 MCP 서버를 설치하고 관리하거나 mcp.json에서 구성할 수 있습니다.

MCP를 사용하는 이유

MCP는 Cursor를 외부 시스템 및 데이터에 연결합니다. 프로젝트 구조를 반복해서 설명하는 대신 사용하는 도구와 직접 연동하세요.

stdout에 출력하거나 HTTP 엔드포인트를 제공할 수 있는 모든 언어로 MCP 서버를 작성할 수 있습니다. Python, JavaScript, Go 등이 있습니다.

공식 플러그인은 Cursor 마켓플레이스에서 둘러보세요. 커뮤니티 플러그인과 MCP 서버는 cursor.directory에서 둘러보세요.

동작 방식

MCP 서버는 프로토콜을 통해 기능을 제공하며, Cursor를 외부 도구 또는 데이터 소스와 연결합니다.

Cursor는 세 가지 전송 방식을 지원합니다.

전송 방식	실행 환경	배포	사용자	입력	인증
`stdio`	로컬	Cursor에서 관리	단일 사용자	셸 명령	수동
`SSE`	로컬/원격	서버로 배포	여러 사용자	SSE 엔드포인트 URL	OAuth
`Streamable HTTP`	로컬/원격	서버로 배포	여러 사용자	HTTP 엔드포인트 URL	OAuth

프로토콜 및 확장 프로그램 지원

Cursor는 다음 MCP 프로토콜 기능 및 확장 프로그램을 지원합니다:

기능	지원	설명
도구	지원됨	AI 모델이 실행할 수 있는 함수
프롬프트	지원됨	사용자를 위한 템플릿 메시지 및 워크플로
리소스	지원됨	읽고 참고할 수 있는 구조화된 데이터 소스
루트	지원됨	URI 또는 파일 시스템 경계에 대해 서버가 시작하는 질의
정보 요청	지원됨	사용자에게 추가 정보를 요청하는 서버 시작 요청
Apps (확장 프로그램)	지원됨	MCP 도구가 반환하는 대화형 UI 뷰

MCP 앱

Cursor는 MCP Apps 확장 프로그램을 지원합니다. MCP 도구는 표준 도구 출력과 함께 대화형 UI를 반환할 수 있습니다.

MCP Apps는 점진적 향상 방식을 따릅니다. 호스트에서 앱 UI를 렌더링할 수 없더라도 동일한 도구는 일반 MCP 응답을 통해 계속 작동합니다.

MCP 서버 설치

원클릭 설치

Cursor 마켓플레이스에서 사용자 지정하기를 통해 원클릭으로 설치할 수 있는 공식 플러그인을 찾아보거나, mcp.json으로 사용자 정의 서버를 구성하세요. 커뮤니티 플러그인과 MCP 서버는 cursor.directory에서 찾아보세요. 마켓플레이스 항목에서 "Add to Cursor"를 클릭해 설치하고 OAuth로 인증하세요.

팀 관리자는 팀 마켓플레이스를 통해 MCP 서버를 배포할 수도 있습니다. 팀에서 배포한 서버는 개인 및 워크스페이스 MCP 서버와 함께 사용자 지정하기에 표시됩니다.

`mcp.json` 사용

JSON 파일로 사용자 정의 MCP 서버를 설정합니다:

CLI Server - Node.js

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

CLI Server - Python

{  "mcpServers": {    "server-name": {      "command": "python",      "args": ["mcp-server.py"],      "env": {        "API_KEY": "value"      }    }  }}

Remote Server

// HTTP 또는 SSE를 사용하는 MCP 서버 - 서버에서 실행{  "mcpServers": {    "server-name": {      "url": "http://localhost:3000/mcp",      "headers": {        "API_KEY": "value"      }    }  }}

원격 서버용 정적 OAuth

OAuth를 사용하는 MCP 서버에서는 동적 클라이언트 등록 대신 mcp.json에 정적 OAuth 클라이언트 자격 증명을 제공할 수 있습니다. 다음과 같은 경우에 사용하세요.

MCP 공급자에서 고정된 Client ID(및 선택적으로 Client Secret)를 제공하는 경우
공급자에서 리디렉션 URL의 허용 목록 등록을 요구하는 경우(예: Figma, Linear)
공급자에서 OAuth 2.0 동적 클라이언트 등록을 지원하지 않는 경우

url을 사용하는 원격 서버 항목에 auth object를 추가하세요:

Remote Server with Static OAuth

{  "mcpServers": {    "oauth-server": {      "url": "https://api.example.com/mcp",      "auth": {        "CLIENT_ID": "your-oauth-client-id",        "CLIENT_SECRET": "your-client-secret",        "scopes": ["read", "write"]      }    }  }}

필드	필수	설명
CLIENT_ID	예	MCP 공급자에서 제공하는 OAuth 2.0 Client ID
CLIENT_SECRET	아니요	OAuth 2.0 Client Secret(공급자가 기밀 클라이언트를 사용하는 경우)
scopes	아니요	요청할 OAuth scope입니다. 생략하면 Cursor가 `/.well-known/oauth-authorization-server`를 통해 `scopes_supported`를 검색합니다

고정 리디렉션 URL

Cursor는 MCP 서버에 고정된 OAuth 리디렉션 URL을 사용합니다. 사용자가 인증하는 각 인터페이스에 대해 콜백을 등록하세요:

https://www.cursor.com/agents/mcp/oauth/callbackhttp://localhost:8787/callback

Web 및 Cursor 에이전트: https://www.cursor.com/agents/mcp/oauth/callback
데스크톱 앱: http://localhost:8787/callback

MCP 제공업체의 OAuth 앱을 구성할 때 사용자가 웹과 데스크톱 모두에서 인증하는 경우, 두 URL을 모두 허용된 리디렉션 URI로 등록하세요. 서버는 OAuth state 파라미터로 식별되므로 이 리디렉션 URL은 모든 MCP 서버에서 사용할 수 있습니다.

구성 값 보간 사용

auth 값은 다른 필드와 마찬가지로 보간을 지원합니다:

{  "mcpServers": {    "oauth-server": {      "url": "https://api.example.com/mcp",      "auth": {        "CLIENT_ID": "${env:MCP_CLIENT_ID}",        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"      }    }  }}

Client ID와 Client Secret을 하드코딩하지 말고 환경 변수를 사용하세요.

STDIO 서버 설정

STDIO 서버(로컬 명령줄 서버)의 경우 mcp.json에서 다음 필드를 설정하세요.

필드	필수	설명	예시
type	예	서버 연결 유형	`"stdio"`
command	예	서버 실행 파일을 시작하는 명령어입니다. 시스템 경로에서 사용할 수 있거나 전체 경로를 지정해야 합니다.	`"npx"`, `"node"`, `"python"`, `"docker"`
args	아니요	명령어에 전달할 인수 배열	`["server.py", "--port", "3000"]`
env	아니요	서버의 환경 변수	`{"API_KEY": "${env:api-key}"}`
envFile	아니요	추가 변수를 로드할 환경 파일의 경로	`".env"`, `"${workspaceFolder}/.env"`

envFile 옵션은 STDIO 서버에서만 사용할 수 있습니다. 원격 서버(HTTP/SSE)는 envFile을 지원하지 않습니다. 원격 서버에서는 셸 프로필 또는 시스템 환경에 설정된 환경 변수를 사용해 구성 값 보간을 사용하세요.

확장 프로그램 API 사용

Cursor는 mcp.json 파일을 수정하지 않고도 MCP 서버를 프로그래밍 방식으로 등록하고 동적으로 구성할 수 있는 확장 프로그램 API를 제공합니다. 이는 엔터프라이즈 환경과 자동화된 설정 워크플로에 특히 유용합니다.

확장 프로그램 API 참고

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 서버는 인증을 위해 환경 변수를 사용합니다. config를 통해 API 키와 토큰을 전달하세요.

Cursor는 OAuth가 필요한 서버를 지원합니다.

엔터프라이즈 관리자 제어

MCP 배포와 MCP 정책은 별도로 구성됩니다. 팀 관리자는 공유 MCP 서버를 배포할 수 있으며, 엔터프라이즈 관리자는 MCP 정책을 설정할 수 있습니다.

팀 MCP 배포

대시보드 > 통합 및 MCP에서 공유 팀 MCP 서버를 구성합니다. 이 서버는 클라우드 에이전트에서 사용할 수 있습니다.

기존 독립형 팀 MCP 서버를 Agent Window, IDE 및 CLI에서 사용할 수 있게 하려면 팀 MCP 서버에서 팀 마켓플레이스에 추가를 선택합니다. Cursor는 클라우드 에이전트의 접근을 중단하지 않고 서버를 기본 팀 마켓플레이스에 연결합니다. 이후 팀원은 사용자 지정하기에서 이를 설치하고 구성할 수 있습니다.

MCP 서버를 Marketplace에 연결해도 모든 사용자에게 설치되거나 활성화되는 것은 아닙니다. 대시보드 > 플러그인에서 Marketplace 접근 및 플러그인 설치 모드를 구성합니다. 전체 절차는 기존 팀 MCP 마이그레이션을 참조하세요.

MCP 허용 목록

엔터프라이즈 관리자는 Cursor 대시보드에서 사용자가 실행할 수 있는 MCP 서버를 제어할 수 있습니다. 팀 설정 > MCP 설정을 열어 팀에서 실행할 수 있는 서버와 도구를 구성하세요. 허용 목록에 추가하면 MCP 구성이 승인됩니다. 서버를 배포하거나 설치하는 것은 아닙니다.

MCP 허용 목록에서 승인할 서버를 지정하세요.

명령 항목은 명령 패턴을 기준으로 로컬 stdio MCP 서버를 승인합니다.
URL 항목은 URL 항목 패턴을 기준으로 원격 HTTP/SSE MCP 서버를 승인합니다.
도구 허용 목록은 승인된 서버에서 자동으로 실행할 수 있는 도구를 제한합니다. 해당 서버의 모든 도구를 허용하려면 도구 허용 목록을 비워 두세요.

네트워크 제어

원격 MCP URL은 구성된 URL 항목 패턴에 따라 제한됩니다.

로컬 명령 기반 MCP 서버는 서버별 네트워크 모드를 사용합니다.

모두 허용: 아웃바운드 네트워크 액세스를 허용합니다.
허용 목록: 목록에 있는 대상에만 접근을 허용합니다.
모두 거부: 아웃바운드 네트워크 액세스를 차단합니다.
샌드박스 없음: 명령 또는 네트워크 샌드박싱 없이 실행합니다.

사용자 MCP 확장 프로그램

관리자는 사용자가 관리자가 정의한 명령 또는 URL 패턴 외부에서 자체 MCP 서버를 구성하도록 허용할 수 있습니다. 관리자 정의 패턴과 일치하지 않는 사용자 MCP의 경우 사용자 MCP 네트워크 차단 목록에서 해당 네트워크 대상에 대한 연결을 차단할 수 있습니다.

채팅에서 MCP 사용

Cursor는 필요에 따라 Available Tools에 나열된 MCP 도구를 자동으로 사용합니다. 여기에는 계획 모드도 포함됩니다. 특정 도구를 이름으로 요청하거나 필요한 작업을 설명하세요. 사이드바의 사용자 지정하기에서 MCP 서버를 활성화하거나 비활성화하세요.

도구 승인

Cursor는 기본적으로 MCP 도구를 사용하기 전에 승인을 요청합니다. 도구 이름 옆의 화살표를 클릭하면 인수를 확인할 수 있습니다.

실행 모드

MCP는 터미널 명령과 동일한 실행 모드를 따릅니다. 예를 들어 Auto-review 모드에서는 허용 목록에 있는 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의 실제 활용 예시는 다음과 같습니다.

Xcode 통합 — Cursor를 Xcode 26.3+에 연결해 빌드, 테스트, SwiftUI 미리보기 및 Apple 문서 검색에 활용
Web Development 가이드 — Linear, Figma 및 브라우저 도구를 개발 워크플로에 통합

FAQ

MCP 서버는 Cursor를 Google Drive, Notion 등의 외부 도구 및 서비스에 연결해 문서와 요구 사항을 코딩 워크플로에 가져옵니다.

다음과 같이 MCP 로그를 확인하세요.

Cursor에서 출력 패널을 엽니다(Cmd+Shift+UCtrl+Shift+U)
드롭다운에서 "MCP Logs"를 선택합니다
연결 오류, 인증 문제 또는 서버 충돌이 있는지 확인합니다

로그에는 서버 초기화, 도구 호출, 오류 메시지가 표시됩니다.

예. 서버를 제거하지 않고 켜거나 끌 수 있습니다.

사이드바에서 사용자 지정하기을 엽니다
변경할 MCP 서버를 찾습니다
토글을 사용해 활성화하거나 비활성화합니다

비활성화된 서버는 로드되지 않으며 채팅에도 표시되지 않습니다. 문제 해결이나 도구 목록을 줄이는 데 유용합니다.

MCP 서버에 문제가 발생하면:

Cursor가 채팅에 오류 메시지를 표시합니다
도구 호출이 실패로 표시됩니다
작업을 다시 시도하거나 자세한 내용은 로그에서 확인할 수 있습니다
다른 MCP 서버는 정상적으로 계속 작동합니다

Cursor는 한 서버의 실패가 다른 서버에 영향을 주지 않도록 격리합니다.

npm 기반 서버의 경우:

사용자 지정하기에서 서버를 제거합니다
npm 캐시를 지웁니다: npm cache clean --force
최신 버전을 받으려면 서버를 다시 추가합니다

사용자 정의 서버의 경우 로컬 파일을 업데이트하고 Cursor를 다시 시작하세요.

예. 단, 보안 모범 사례를 따르세요.

시크릿에는 환경 변수를 사용하고 절대 하드코딩하지 마세요
민감한 서버는 stdio 전송 방식을 사용해 로컬에서 실행하세요
API 키 권한을 필요한 최소한으로 제한하세요
민감한 시스템에 연결하기 전에 서버 코드를 검토하세요
격리된 환경에서 서버를 실행하는 것을 고려하세요

모델 컨텍스트 프로토콜(MCP)

MCP란 무엇인가요?

MCP를 사용하는 이유

MCP는 Cursor를 외부 시스템 및 데이터에 연결합니다. 프로젝트 구조를 반복해서 설명하는 대신 사용하는 도구와 직접 연동하세요.

stdout에 출력하거나 HTTP 엔드포인트를 제공할 수 있는 모든 언어로 MCP 서버를 작성할 수 있습니다. Python, JavaScript, Go 등이 있습니다.

공식 플러그인은 Cursor 마켓플레이스에서 둘러보세요. 커뮤니티 플러그인과 MCP 서버는 cursor.directory에서 둘러보세요.

동작 방식

MCP 서버는 프로토콜을 통해 기능을 제공하며, Cursor를 외부 도구 또는 데이터 소스와 연결합니다.

Cursor는 세 가지 전송 방식을 지원합니다.

전송 방식	실행 환경	배포	사용자	입력	인증
`stdio`	로컬	Cursor에서 관리	단일 사용자	셸 명령	수동
`SSE`	로컬/원격	서버로 배포	여러 사용자	SSE 엔드포인트 URL	OAuth
`Streamable HTTP`	로컬/원격	서버로 배포	여러 사용자	HTTP 엔드포인트 URL	OAuth

프로토콜 및 확장 프로그램 지원

Cursor는 다음 MCP 프로토콜 기능 및 확장 프로그램을 지원합니다:

기능	지원	설명
도구	지원됨	AI 모델이 실행할 수 있는 함수
프롬프트	지원됨	사용자를 위한 템플릿 메시지 및 워크플로
리소스	지원됨	읽고 참고할 수 있는 구조화된 데이터 소스
루트	지원됨	URI 또는 파일 시스템 경계에 대해 서버가 시작하는 질의
정보 요청	지원됨	사용자에게 추가 정보를 요청하는 서버 시작 요청
Apps (확장 프로그램)	지원됨	MCP 도구가 반환하는 대화형 UI 뷰

MCP 앱

Cursor는 MCP Apps 확장 프로그램을 지원합니다. MCP 도구는 표준 도구 출력과 함께 대화형 UI를 반환할 수 있습니다.

MCP Apps는 점진적 향상 방식을 따릅니다. 호스트에서 앱 UI를 렌더링할 수 없더라도 동일한 도구는 일반 MCP 응답을 통해 계속 작동합니다.

MCP 서버 설치

원클릭 설치

`mcp.json` 사용

JSON 파일로 사용자 정의 MCP 서버를 설정합니다:

CLI Server - Node.js

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

CLI Server - Python

{  "mcpServers": {    "server-name": {      "command": "python",      "args": ["mcp-server.py"],      "env": {        "API_KEY": "value"      }    }  }}

Remote Server

// HTTP 또는 SSE를 사용하는 MCP 서버 - 서버에서 실행{  "mcpServers": {    "server-name": {      "url": "http://localhost:3000/mcp",      "headers": {        "API_KEY": "value"      }    }  }}

원격 서버용 정적 OAuth

MCP 공급자에서 고정된 Client ID(및 선택적으로 Client Secret)를 제공하는 경우
공급자에서 리디렉션 URL의 허용 목록 등록을 요구하는 경우(예: Figma, Linear)
공급자에서 OAuth 2.0 동적 클라이언트 등록을 지원하지 않는 경우

url을 사용하는 원격 서버 항목에 auth object를 추가하세요:

Remote Server with Static OAuth

{  "mcpServers": {    "oauth-server": {      "url": "https://api.example.com/mcp",      "auth": {        "CLIENT_ID": "your-oauth-client-id",        "CLIENT_SECRET": "your-client-secret",        "scopes": ["read", "write"]      }    }  }}

필드	필수	설명
CLIENT_ID	예	MCP 공급자에서 제공하는 OAuth 2.0 Client ID
CLIENT_SECRET	아니요	OAuth 2.0 Client Secret(공급자가 기밀 클라이언트를 사용하는 경우)
scopes	아니요	요청할 OAuth scope입니다. 생략하면 Cursor가 `/.well-known/oauth-authorization-server`를 통해 `scopes_supported`를 검색합니다

고정 리디렉션 URL

Cursor는 MCP 서버에 고정된 OAuth 리디렉션 URL을 사용합니다. 사용자가 인증하는 각 인터페이스에 대해 콜백을 등록하세요:

https://www.cursor.com/agents/mcp/oauth/callbackhttp://localhost:8787/callback

Web 및 Cursor 에이전트: https://www.cursor.com/agents/mcp/oauth/callback
데스크톱 앱: http://localhost:8787/callback

구성 값 보간 사용

auth 값은 다른 필드와 마찬가지로 보간을 지원합니다:

{  "mcpServers": {    "oauth-server": {      "url": "https://api.example.com/mcp",      "auth": {        "CLIENT_ID": "${env:MCP_CLIENT_ID}",        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"      }    }  }}

Client ID와 Client Secret을 하드코딩하지 말고 환경 변수를 사용하세요.

STDIO 서버 설정

STDIO 서버(로컬 명령줄 서버)의 경우 mcp.json에서 다음 필드를 설정하세요.

필드	필수	설명	예시
type	예	서버 연결 유형	`"stdio"`
command	예	서버 실행 파일을 시작하는 명령어입니다. 시스템 경로에서 사용할 수 있거나 전체 경로를 지정해야 합니다.	`"npx"`, `"node"`, `"python"`, `"docker"`
args	아니요	명령어에 전달할 인수 배열	`["server.py", "--port", "3000"]`
env	아니요	서버의 환경 변수	`{"API_KEY": "${env:api-key}"}`
envFile	아니요	추가 변수를 로드할 환경 파일의 경로	`".env"`, `"${workspaceFolder}/.env"`

확장 프로그램 API 사용

확장 프로그램 API 참고

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}"      }    }  }}

명령 항목은 명령 패턴을 기준으로 로컬 stdio MCP 서버를 승인합니다.
URL 항목은 URL 항목 패턴을 기준으로 원격 HTTP/SSE MCP 서버를 승인합니다.
도구 허용 목록은 승인된 서버에서 자동으로 실행할 수 있는 도구를 제한합니다. 해당 서버의 모든 도구를 허용하려면 도구 허용 목록을 비워 두세요.

네트워크 제어

원격 MCP URL은 구성된 URL 항목 패턴에 따라 제한됩니다.

로컬 명령 기반 MCP 서버는 서버별 네트워크 모드를 사용합니다.

모두 허용: 아웃바운드 네트워크 액세스를 허용합니다.
허용 목록: 목록에 있는 대상에만 접근을 허용합니다.
모두 거부: 아웃바운드 네트워크 액세스를 차단합니다.
샌드박스 없음: 명령 또는 네트워크 샌드박싱 없이 실행합니다.

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",      },    ],  };});

보안 고려 사항

MCP 서버를 설치할 때는 다음 보안 수칙을 따르세요:

출처 확인: 신뢰할 수 있는 개발자와 리포지토리에서 제공하는 MCP 서버만 설치하세요
권한 검토: 서버가 접근할 데이터와 API를 확인하세요
API 키 제한: 필요한 최소 권한만 부여된 제한적 API 키를 사용하세요
코드 감사: 중요한 통합의 경우 서버의 소스 코드를 검토하세요

MCP 서버는 사용자를 대신해 외부 서비스에 접근하고 코드를 실행할 수 있습니다. 설치하기 전에 서버가 수행하는 작업을 항상 확인하세요.

실제 활용 예시

MCP의 실제 활용 예시는 다음과 같습니다.

Xcode 통합 — Cursor를 Xcode 26.3+에 연결해 빌드, 테스트, SwiftUI 미리보기 및 Apple 문서 검색에 활용
Web Development 가이드 — Linear, Figma 및 브라우저 도구를 개발 워크플로에 통합

FAQ

MCP 서버는 Cursor를 Google Drive, Notion 등의 외부 도구 및 서비스에 연결해 문서와 요구 사항을 코딩 워크플로에 가져옵니다.

다음과 같이 MCP 로그를 확인하세요.

Cursor에서 출력 패널을 엽니다(Cmd+Shift+UCtrl+Shift+U)
드롭다운에서 "MCP Logs"를 선택합니다
연결 오류, 인증 문제 또는 서버 충돌이 있는지 확인합니다

로그에는 서버 초기화, 도구 호출, 오류 메시지가 표시됩니다.

예. 서버를 제거하지 않고 켜거나 끌 수 있습니다.

사이드바에서 사용자 지정하기을 엽니다
변경할 MCP 서버를 찾습니다
토글을 사용해 활성화하거나 비활성화합니다

비활성화된 서버는 로드되지 않으며 채팅에도 표시되지 않습니다. 문제 해결이나 도구 목록을 줄이는 데 유용합니다.

MCP 서버에 문제가 발생하면:

Cursor가 채팅에 오류 메시지를 표시합니다
도구 호출이 실패로 표시됩니다
작업을 다시 시도하거나 자세한 내용은 로그에서 확인할 수 있습니다
다른 MCP 서버는 정상적으로 계속 작동합니다

Cursor는 한 서버의 실패가 다른 서버에 영향을 주지 않도록 격리합니다.

npm 기반 서버의 경우:

사용자 지정하기에서 서버를 제거합니다
npm 캐시를 지웁니다: npm cache clean --force
최신 버전을 받으려면 서버를 다시 추가합니다

사용자 정의 서버의 경우 로컬 파일을 업데이트하고 Cursor를 다시 시작하세요.

예. 단, 보안 모범 사례를 따르세요.

시크릿에는 환경 변수를 사용하고 절대 하드코딩하지 마세요
민감한 서버는 stdio 전송 방식을 사용해 로컬에서 실행하세요
API 키 권한을 필요한 최소한으로 제한하세요
민감한 시스템에 연결하기 전에 서버 코드를 검토하세요
격리된 환경에서 서버를 실행하는 것을 고려하세요

모델 컨텍스트 프로토콜(MCP)

MCP란 무엇인가요?

MCP를 사용하는 이유

MCP는 Cursor를 외부 시스템 및 데이터에 연결합니다. 프로젝트 구조를 반복해서 설명하는 대신 사용하는 도구와 직접 연동하세요.

stdout에 출력하거나 HTTP 엔드포인트를 제공할 수 있는 모든 언어로 MCP 서버를 작성할 수 있습니다. Python, JavaScript, Go 등이 있습니다.

공식 플러그인은 Cursor 마켓플레이스에서 둘러보세요. 커뮤니티 플러그인과 MCP 서버는 cursor.directory에서 둘러보세요.

동작 방식

MCP 서버는 프로토콜을 통해 기능을 제공하며, Cursor를 외부 도구 또는 데이터 소스와 연결합니다.

Cursor는 세 가지 전송 방식을 지원합니다.

전송 방식	실행 환경	배포	사용자	입력	인증
`stdio`	로컬	Cursor에서 관리	단일 사용자	셸 명령	수동
`SSE`	로컬/원격	서버로 배포	여러 사용자	SSE 엔드포인트 URL	OAuth
`Streamable HTTP`	로컬/원격	서버로 배포	여러 사용자	HTTP 엔드포인트 URL	OAuth

프로토콜 및 확장 프로그램 지원

Cursor는 다음 MCP 프로토콜 기능 및 확장 프로그램을 지원합니다:

기능	지원	설명
도구	지원됨	AI 모델이 실행할 수 있는 함수
프롬프트	지원됨	사용자를 위한 템플릿 메시지 및 워크플로
리소스	지원됨	읽고 참고할 수 있는 구조화된 데이터 소스
루트	지원됨	URI 또는 파일 시스템 경계에 대해 서버가 시작하는 질의
정보 요청	지원됨	사용자에게 추가 정보를 요청하는 서버 시작 요청
Apps (확장 프로그램)	지원됨	MCP 도구가 반환하는 대화형 UI 뷰

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

CLI Server - Python

{  "mcpServers": {    "server-name": {      "command": "python",      "args": ["mcp-server.py"],      "env": {        "API_KEY": "value"      }    }  }}

Remote Server

// HTTP 또는 SSE를 사용하는 MCP 서버 - 서버에서 실행{  "mcpServers": {    "server-name": {      "url": "http://localhost:3000/mcp",      "headers": {        "API_KEY": "value"      }    }  }}

원격 서버용 정적 OAuth

MCP 공급자에서 고정된 Client ID(및 선택적으로 Client Secret)를 제공하는 경우
공급자에서 리디렉션 URL의 허용 목록 등록을 요구하는 경우(예: Figma, Linear)
공급자에서 OAuth 2.0 동적 클라이언트 등록을 지원하지 않는 경우

url을 사용하는 원격 서버 항목에 auth object를 추가하세요:

Remote Server with Static OAuth

{  "mcpServers": {    "oauth-server": {      "url": "https://api.example.com/mcp",      "auth": {        "CLIENT_ID": "your-oauth-client-id",        "CLIENT_SECRET": "your-client-secret",        "scopes": ["read", "write"]      }    }  }}

필드	필수	설명
CLIENT_ID	예	MCP 공급자에서 제공하는 OAuth 2.0 Client ID
CLIENT_SECRET	아니요	OAuth 2.0 Client Secret(공급자가 기밀 클라이언트를 사용하는 경우)
scopes	아니요	요청할 OAuth scope입니다. 생략하면 Cursor가 `/.well-known/oauth-authorization-server`를 통해 `scopes_supported`를 검색합니다

고정 리디렉션 URL

Cursor는 MCP 서버에 고정된 OAuth 리디렉션 URL을 사용합니다. 사용자가 인증하는 각 인터페이스에 대해 콜백을 등록하세요:

https://www.cursor.com/agents/mcp/oauth/callbackhttp://localhost:8787/callback

Web 및 Cursor 에이전트: https://www.cursor.com/agents/mcp/oauth/callback
데스크톱 앱: http://localhost:8787/callback

구성 값 보간 사용

auth 값은 다른 필드와 마찬가지로 보간을 지원합니다:

{  "mcpServers": {    "oauth-server": {      "url": "https://api.example.com/mcp",      "auth": {        "CLIENT_ID": "${env:MCP_CLIENT_ID}",        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"      }    }  }}

Client ID와 Client Secret을 하드코딩하지 말고 환경 변수를 사용하세요.

STDIO 서버 설정

STDIO 서버(로컬 명령줄 서버)의 경우 mcp.json에서 다음 필드를 설정하세요.

필드	필수	설명	예시
type	예	서버 연결 유형	`"stdio"`
command	예	서버 실행 파일을 시작하는 명령어입니다. 시스템 경로에서 사용할 수 있거나 전체 경로를 지정해야 합니다.	`"npx"`, `"node"`, `"python"`, `"docker"`
args	아니요	명령어에 전달할 인수 배열	`["server.py", "--port", "3000"]`
env	아니요	서버의 환경 변수	`{"API_KEY": "${env:api-key}"}`
envFile	아니요	추가 변수를 로드할 환경 파일의 경로	`".env"`, `"${workspaceFolder}/.env"`

확장 프로그램 API 사용

확장 프로그램 API 참고

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}"      }    }  }}

명령 항목은 명령 패턴을 기준으로 로컬 stdio MCP 서버를 승인합니다.
URL 항목은 URL 항목 패턴을 기준으로 원격 HTTP/SSE MCP 서버를 승인합니다.
도구 허용 목록은 승인된 서버에서 자동으로 실행할 수 있는 도구를 제한합니다. 해당 서버의 모든 도구를 허용하려면 도구 허용 목록을 비워 두세요.

네트워크 제어

원격 MCP URL은 구성된 URL 항목 패턴에 따라 제한됩니다.

로컬 명령 기반 MCP 서버는 서버별 네트워크 모드를 사용합니다.

모두 허용: 아웃바운드 네트워크 액세스를 허용합니다.
허용 목록: 목록에 있는 대상에만 접근을 허용합니다.
모두 거부: 아웃바운드 네트워크 액세스를 차단합니다.
샌드박스 없음: 명령 또는 네트워크 샌드박싱 없이 실행합니다.

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",      },    ],  };});

보안 고려 사항

MCP 서버를 설치할 때는 다음 보안 수칙을 따르세요:

출처 확인: 신뢰할 수 있는 개발자와 리포지토리에서 제공하는 MCP 서버만 설치하세요
권한 검토: 서버가 접근할 데이터와 API를 확인하세요
API 키 제한: 필요한 최소 권한만 부여된 제한적 API 키를 사용하세요
코드 감사: 중요한 통합의 경우 서버의 소스 코드를 검토하세요

MCP 서버는 사용자를 대신해 외부 서비스에 접근하고 코드를 실행할 수 있습니다. 설치하기 전에 서버가 수행하는 작업을 항상 확인하세요.

실제 활용 예시

MCP의 실제 활용 예시는 다음과 같습니다.

Xcode 통합 — Cursor를 Xcode 26.3+에 연결해 빌드, 테스트, SwiftUI 미리보기 및 Apple 문서 검색에 활용
Web Development 가이드 — Linear, Figma 및 브라우저 도구를 개발 워크플로에 통합

FAQ

MCP 서버는 Cursor를 Google Drive, Notion 등의 외부 도구 및 서비스에 연결해 문서와 요구 사항을 코딩 워크플로에 가져옵니다.

다음과 같이 MCP 로그를 확인하세요.

Cursor에서 출력 패널을 엽니다(Cmd+Shift+UCtrl+Shift+U)
드롭다운에서 "MCP Logs"를 선택합니다
연결 오류, 인증 문제 또는 서버 충돌이 있는지 확인합니다

로그에는 서버 초기화, 도구 호출, 오류 메시지가 표시됩니다.

예. 서버를 제거하지 않고 켜거나 끌 수 있습니다.

사이드바에서 사용자 지정하기을 엽니다
변경할 MCP 서버를 찾습니다
토글을 사용해 활성화하거나 비활성화합니다

비활성화된 서버는 로드되지 않으며 채팅에도 표시되지 않습니다. 문제 해결이나 도구 목록을 줄이는 데 유용합니다.

MCP 서버에 문제가 발생하면:

Cursor가 채팅에 오류 메시지를 표시합니다
도구 호출이 실패로 표시됩니다
작업을 다시 시도하거나 자세한 내용은 로그에서 확인할 수 있습니다
다른 MCP 서버는 정상적으로 계속 작동합니다

Cursor는 한 서버의 실패가 다른 서버에 영향을 주지 않도록 격리합니다.

npm 기반 서버의 경우:

사용자 지정하기에서 서버를 제거합니다
npm 캐시를 지웁니다: npm cache clean --force
최신 버전을 받으려면 서버를 다시 추가합니다

사용자 정의 서버의 경우 로컬 파일을 업데이트하고 Cursor를 다시 시작하세요.

예. 단, 보안 모범 사례를 따르세요.

시크릿에는 환경 변수를 사용하고 절대 하드코딩하지 마세요
민감한 서버는 stdio 전송 방식을 사용해 로컬에서 실행하세요
API 키 권한을 필요한 최소한으로 제한하세요
민감한 시스템에 연결하기 전에 서버 코드를 검토하세요
격리된 환경에서 서버를 실행하는 것을 고려하세요

Command Palette

시작하기

에이전트

사용자 지정

클라우드 에이전트

연동

SDK

CLI

팀 및 엔터프라이즈

모델 컨텍스트 프로토콜(MCP)

MCP 서버는 어떤 용도로 사용하나요?

MCP 서버 문제는 어떻게 디버깅하나요?

MCP 서버를 일시적으로 비활성화할 수 있나요?

MCP 서버가 충돌하거나 시간 초과되면 어떻게 되나요?

MCP 서버는 어떻게 업데이트하나요?

민감한 데이터와 함께 MCP 서버를 사용할 수 있나요?

Command Palette

시작하기

에이전트

사용자 지정

클라우드 에이전트

연동

SDK

CLI

팀 및 엔터프라이즈

모델 컨텍스트 프로토콜(MCP)

MCP 서버는 어떤 용도로 사용하나요?

MCP 서버 문제는 어떻게 디버깅하나요?

MCP 서버를 일시적으로 비활성화할 수 있나요?

MCP 서버가 충돌하거나 시간 초과되면 어떻게 되나요?

MCP 서버는 어떻게 업데이트하나요?

민감한 데이터와 함께 MCP 서버를 사용할 수 있나요?

Command Palette

시작하기

에이전트

사용자 지정

클라우드 에이전트

연동

SDK

CLI

팀 및 엔터프라이즈

모델 컨텍스트 프로토콜(MCP)

MCP 서버는 어떤 용도로 사용하나요?

MCP 서버 문제는 어떻게 디버깅하나요?

MCP 서버를 일시적으로 비활성화할 수 있나요?

MCP 서버가 충돌하거나 시간 초과되면 어떻게 되나요?

MCP 서버는 어떻게 업데이트하나요?

민감한 데이터와 함께 MCP 서버를 사용할 수 있나요?