Cursor Agent가 GitHub·Notion·데이터베이스 같은 외부 도구를 직접 사용하게 하려면?
Cursor는 MCP Server를 Marketplace에서 원클릭으로 설치하거나
mcp.json에 직접 등록할 수 있습니다. 연결된 Tool은 Agent 대화에서 필요한 순간 선택되며, 사용자는 실행 인수와 권한을 검토할 수 있습니다.이번 글에서는 설치, 로컬·원격 설정, 적용 범위, OAuth 인증, 첫 테스트와 오류 해결을 안전한 순서로 따라갑니다. 내용은 2026년 9월 Cursor 공식 문서를 기준으로 작성했습니다.
1. Cursor에서 MCP가 작동하는 구조
Cursor는 MCP Client가 포함된 Host 역할을 합니다. Agent가 사용자의 요청을 해석하고, 연결된 MCP Server가 공개한 Tool 가운데 적합한 기능을 선택합니다. Server는 로컬 프로세스로 실행될 수도 있고 원격 서비스에서 운영될 수도 있습니다.
예를 들어 “최근 오류와 관련된 코드를 찾아 수정안을 제안해 줘”라고 요청하면 Agent가 오류 추적 MCP Tool로 데이터를 읽고, 코드베이스를 검색한 뒤 수정안을 만들 수 있습니다. 다만 실제로 어떤 도구를 사용할 수 있는지는 설치한 Server와 계정 권한에 따라 달라집니다.
Server의 출처와 운영 주체, 요청하는 OAuth 권한, 데이터 전송 범위를 먼저 확인하세요. 처음에는 읽기 전용 권한으로 연결하고 삭제·배포·발송 같은 변경 기능은 별도로 통제하는 편이 안전합니다.
2. 시작 전 준비 사항 확인하기
Cursor를 최신 안정 버전으로 업데이트하고 MCP를 사용할 프로젝트를 엽니다. 로컬 Server를 연결한다면 해당 Server가 요구하는 Node.js, Python 또는 실행 바이너리도 준비해야 합니다.
MCP Server 안내 페이지가 다른 클라이언트용 JSON만 제공하더라도 핵심은 같습니다. 로컬 Server라면 command와 args, 원격 Server라면 url과 인증 정보를 찾아 Cursor 형식에 맞게 등록합니다.
3. Marketplace에서 원클릭 설치하기
가장 쉬운 방법은 Cursor Marketplace 또는 Customize 화면에서 Server를 선택하는 것입니다. 현재 공식 안내의 기본 흐름은 다음과 같습니다.
Marketplace의 제공자 정보와 연결 URL, 요청 권한을 확인하고, 처음에는 데이터 조회처럼 결과를 되돌리기 쉬운 작업으로 검증하세요.
4. 로컬 stdio Server를 mcp.json에 등록하기
Marketplace에 없는 Server나 직접 만든 Server는 mcp.json으로 설정할 수 있습니다. 로컬 stdio Server에는 실행 프로그램을 뜻하는 command와 인수 배열인 args를 작성합니다.
위 패키지명은 구조를 보여 주는 자리 표시자입니다. 실제 설정에는 연결하려는 Server의 공식 문서에 있는 패키지명과 인수를 사용하세요. API 키가 필요하다면 env에 추가할 수 있습니다.
YOUR_KEY는 예시이며 실제 비밀값을 Git에 올리면 안 됩니다.프로젝트용
.cursor/mcp.json은 팀과 공유될 수 있습니다. Server가 지원한다면 환경 변수 참조나 별도의 비밀 관리 방식을 사용하고, 발급한 키에는 필요한 최소 권한만 부여하세요.5. 원격 HTTP Server와 OAuth 연결하기
클라우드에서 운영되는 MCP Server는 실행 명령 대신 url을 사용합니다. 현재 Cursor 문서는 Streamable HTTP와 SSE 전송을 지원하며, Server 안내에 표시된 정확한 엔드포인트를 입력해야 합니다.
OAuth를 지원하는 Server라면 Cursor의 연결 화면에서 로그인 버튼 또는 인증 안내가 표시될 수 있습니다. 브라우저가 열리면 올바른 계정인지, 읽기·쓰기 중 어떤 권한을 요청하는지 확인하고 승인합니다.
고정 토큰 헤더가 필요한 Server는 공식 안내에 따라 headers를 추가할 수 있습니다.
장기 토큰을 설정 파일에 직접 기록하는 방식보다 사용자가 권한 범위를 확인하고 취소할 수 있습니다. 어떤 방식이든 실제 보안 수준은 Server 구현과 토큰 저장 정책에 따라 달라집니다.
6. 프로젝트 설정과 전역 설정 구분하기
Cursor의 수동 MCP 설정 위치는 두 가지입니다. 프로젝트에만 필요한 도구인지, 내 모든 프로젝트에서 사용할 개인 도구인지에 따라 파일 위치를 선택합니다.
| 구분 | 설정 위치 | 적합한 상황 | 공유 여부 |
|---|---|---|---|
| 프로젝트 | .cursor/mcp.json |
특정 저장소에 필요한 도구를 팀과 동일하게 사용 | Git에 포함하면 공유 가능. 비밀값은 제외 |
| 전역 | ~/.cursor/mcp.json |
내 여러 프로젝트에서 반복 사용하는 개인 도구 | 현재 사용자 컴퓨터에만 저장 |
Cursor는 두 설정을 함께 읽습니다. 같은 이름의 Server가 양쪽에 있으면 공식 문서 기준으로 프로젝트 설정이 전역 설정보다 우선합니다. 팀에서 같은 Server를 사용하려면 이름과 목적을 문서화하고, 개인 설정과 충돌하지 않도록 관리하세요.
.cursor/mcp.json을 바로 신뢰하지 마세요.로컬 stdio 설정의
command와 args는 내 컴퓨터에서 프로그램을 실행할 수 있습니다. 클론한 프로젝트에서는 명령과 URL, 환경 변수 요구사항을 먼저 읽고 필요한 Server만 활성화하세요.7. Agent에서 Tool을 확인하고 테스트하기
설정을 저장한 뒤 Cursor를 다시 시작하거나 MCP 목록에서 Server를 다시 연결합니다. Agent의 도구 목록에서 Server와 Tool이 나타나는지 확인한 다음 읽기 전용 요청으로 첫 테스트를 진행합니다.
문서 검색 Server라면 다음처럼 범위와 금지 행동을 함께 지정할 수 있습니다.
Cursor는 기본적으로 MCP Tool 실행 전 승인을 요청합니다. 최신 버전에서는 Settings의 Approvals & Execution에서 Auto-review 또는 Allowlist 같은 모드를 제공할 수 있습니다. 화면과 기본값은 버전에 따라 달라질 수 있으므로, 자동 실행 범위를 넓히기 전 각 Tool의 부작용을 확인하세요.
조회 도구와 변경 도구를 구분하고, 반복적으로 안전성이 확인된 도구만 최소 범위로 허용합니다. 데이터 삭제, 배포, 결제, 메시지 발송처럼 외부 상태를 바꾸는 Tool은 실행 전 사용자 확인을 유지하는 편이 안전합니다.
8. 연결이 안 될 때 확인할 항목
| 증상 | 가능한 원인 | 확인 방법 |
|---|---|---|
| Server가 목록에 없음 | 파일 위치·JSON 문법 오류, 저장되지 않은 설정 | 프로젝트 또는 전역 경로를 다시 확인하고 JSON 괄호와 쉼표를 검사합니다. |
| 로컬 Server 연결 실패 | Node·Python·바이너리 누락, 잘못된 command와 args | 같은 실행 명령을 터미널에서 직접 실행하고 런타임 버전을 확인합니다. |
| 원격 Server 연결 실패 | 잘못된 URL, 프록시·방화벽, Server 장애 | 공식 엔드포인트와 네트워크 정책을 확인하고 서비스 상태를 점검합니다. |
| 인증 반복 또는 401 | OAuth 세션 만료, 토큰 오류, 권한 부족 | 연결을 다시 인증하고 계정·권한 범위·헤더 공백을 확인합니다. |
| 환경 변수를 못 읽음 | GUI로 실행한 Cursor에 셸 환경이 전달되지 않음 | 환경 변수를 운영체제에서 사용할 수 있게 설정한 뒤 Cursor를 재시작합니다. |
| Tool이 호출되지 않음 | 도구 비활성화, 모호한 요청, 승인 정책 | Agent 도구 목록에서 활성화를 확인하고 Tool 이름과 목적을 명시해 요청합니다. |
MCP Logs 확인하기
Cursor 공식 안내에 따르면 Windows와 Linux에서는 Ctrl + Shift + U, macOS에서는 Cmd + Shift + U로 Output 패널을 열고 출력 채널에서 MCP Logs를 선택할 수 있습니다. 프로세스 시작 오류, 연결 실패와 인증 문제를 확인하되 로그를 공유할 때는 토큰과 개인 정보를 가리세요.
설정 경로와 JSON 문법 → 실행 명령 또는 URL → 런타임과 환경 변수 → 인증 → 네트워크 → MCP Logs 순으로 확인하면 원인을 좁히기 쉽습니다.
9. 핵심 정리
신뢰할 Server 선택 원클릭 또는 mcp.json 프로젝트·전역 범위 인증·Tool 확인 읽기부터 테스트
Marketplace의 Add to Cursor가 가장 간단하고, 직접 설정할 때는 로컬 Server에
command와 args, 원격 Server에 url을 사용합니다. 팀 공유는 .cursor/mcp.json, 개인 공통 설정은 ~/.cursor/mcp.json에 두며, 실행 전 도구 인수와 권한을 확인합니다.MCP를 연결했다고 Agent의 판단이 항상 정확해지는 것은 아닙니다. Server가 반환한 데이터와 모델의 해석에는 오류가 있을 수 있으므로 중요한 수정·배포·발송 작업은 원본과 변경 내용을 검증한 뒤 승인하세요.
다음 글에서는 OpenAI Codex에 MCP Server를 연결하고 설정 범위와 상태를 확인하는 방법을 다룹니다.
🔗 MCP 완전정복 시리즈
참고: Cursor 공식 MCP integrations 문서, Cursor 공식 CLI MCP 문서, Cursor 공식 permissions.json 문서, Cursor 공식 MCP Servers 목록
확인일: 2026-09-19 · Cursor UI, 승인 모드와 지원 전송 방식은 업데이트될 수 있으므로 실제 설정 전 최신 공식 문서를 확인하세요.