Cursor와 Claude Code를 MCP를 통해 내부 API에 연결하는 방법 (단계별)

회사 API를 대상으로 코딩 에이전트를 사용하는 첫 주는 항상 비슷합니다: 문서(docs) URL을 프롬프트에 붙여넣고, 기본 경로(base path)를 수정하고, 인증 헤더(auth header)를 수정하고, 페이지네이션 유형(pagination type)을 수정하고, 엔벨로프 래퍼(envelope wrapper)를 수정하며, 매번 새로운 세션과 새로운 도구마다 반복합니다. 에이전트는 월별로 바뀝니다 — Cursor, Claude Code, 다음에 나올 것이 무엇이든 간에 — 하지만 통합 작업은 계속해서 다시 수행해야 합니다. Model Context Protocol (MCP)은 API가 한 번만 발견 가능하도록 존재하는 것입니다. 이 글에서는 자격 증명 범위 지정(credential scoping) 및 검증 단계까지 포함하여 실제 내부 API를 Cursor와 Claude Code 모두에 MCP를 통해 연결하는 과정을 안내합니다.

시작하기 전에 필요한 것들

• API용 OpenAPI 문서: 3.1 또는 3.2가 선호됩니다. 완벽할 필요는 없지만, operationId는 고유하고 동사(verb)-우선이어야 하며, 요청 본문(request bodies)은 스키마를 가져야 하고, 열거형(enums)은 실제 열거형이어야 합니다 — 에이전트는 여기서 선택합니다.
• MCP로 제공할 방법: spec 파일에서 실행되는 로컬 서버 또는 토큰을 가진 호스팅된 MCP 엔드포인트.
• 샌드박스 대상(sandbox target): 에이전트의 첫 주는 절대 프로덕션 쓰기 작업(production write operations)을 가리켜서는 안 됩니다. 스테이징 서버, 샌드박스 조직, 또는 spec 기반 목업(mock)이 올바른 첫 번째 피어입니다.
• 범위 지정된 자격 증명(Scoped credentials): 개인 관리자 토큰이 아닌 에이전트를 위한 토큰.

단계 1: 스펙을 로컬에서 제공하기

로컬 MCP 서버는 spec 파일을 읽고, 표준 입출력(stdio)을 통해 작업을 도구(tools)로 노출합니다. 이것이 데스크톱 에이전트 클라이언트가 로컬 기능을 생성하는 방식입니다:

{
  "mcpServers": {
    "billing-api": {
...

토큰은 서버 프로세스 환경(environment)에 존재하며, spec, 프롬프트 또는 커밋된 코드에는 절대 포함되지 않습니다. 만약 spec이 여러 서버를 문서화한다면, 에이전트가 스테이징을 두 번째로 나열했다는 이유로 프로덕션으로 벗어나지 못하도록 기본 URL을 명시적으로 지정해야 합니다.

로컬 프로세스를 모든 개발자가 실행하는 것을 원하지 않는 팀의 경우, 호스팅된(hosted) 등가물은 사용자별 또는 통합별 토큰으로 인증되는 HTTPS MCP 엔드포인트입니다. 이 경우 클라이언트 설정에는 생성된 명령 대신 URL과 Authorization 헤더를 포함하게 됩니다.

2단계: Cursor에 등록하기

Cursor는 설정 UI나 프로젝트 레벨의 .cursor/mcp.json에서 MCP 구성을 읽어옵니다 (내부 API의 경우, 이 저장소와 함께 이동하므로 프로젝트 레벨이 올바른 선택입니다):

{
  "mcpServers": {
    "billing-api": {
...

환경 변수 확장은 비밀 정보를 git에서 제외합니다. 저장한 후, Cursor의 MCP 패널에는 노출된 작업(operation)마다 하나의 항목으로 청구 도구가 나열되어야 합니다. 개수가 의도했던 작업 세트와 일치하는지 확인하세요 (필터링에 대한 5단계를 참조).

3단계: Claude Code에 등록하기

Claude Code는 CLI/설정 흐름을 통해 MCP 서버를 구성하며, 동일한 논리적 항목을 생성합니다:

claude mcp add billing-api \
  --env BILLING_API_TOKEN \
  --env PD_API_BASE_URL=https://staging.api.example.com \
...

호스팅된 엔드포인트의 경우, 엔드포인트 URL과 bearer 토큰을 가진 HTTP 유형 서버를 추가합니다. 그러면 에이전트가 프로세스를 생성하는 대신 스트리밍 가능한(streamable) HTTP를 통해 연결됩니다. 도구가 이 코드베이스에서 작업할 때만 나타나도록 설정을 프로젝트 디렉터리에 범위 지정(--scope project)하여, 모든 내부 API에 대한 전역 등록은 너무 커서 선택 품질이 저하되는 도구 목록을 만듭니다.

4단계: 엔지니어처럼 연결 확인하기

'도구가 나타났다'는 사실만 믿지 마세요. 두 클라이언트 모두에서 이 체크리스트를 실행해 보세요:

1. Discovery: tool count는 노출된 operation 개수와 일치해야 하며, 이름은 operationId여야 하고, 설명(description)이 존재해야 합니다.
2. 읽기 호출 (A read call): 에이전트에게 리소스 목록을 요청하도록 지시하고, 이 요청이 올바른 헤더를 가지고 스테이징 환경에 도달하며 파싱된 데이터를 반환하는지 확인합니다.
3. 유효성 검사 실패 (A validation failure): 의도적으로 잘못된 타입(정수형이 필요한 곳에 문자열을 사용하는 등)으로 툴 호출을 요청해봅니다. MCP 서버는 스키마 오류와 함께 사전 비행(pre-flight) 단계에서 해당 호출을 거부해야 합니다. 만약 요청이 API에 도달하여 422를 반환한다면, 유효성 검사가 제대로 연결되지 않은 것입니다.
4. 인증 실패 (Auth failure): 토큰을 제거하고, 멈추거나 HTML 로그인 페이지가 나오는 대신 명확하게 읽을 수 있는 인증 오류 메시지가 나오는지 확인합니다.
5. 쓰기 호출 (A write call): 샌드박스에 하나를 생성(create)해보고, 본문(body)이 문서화된 콘텐츠 타입과 함께 도착했는지, 그리고 에이전트가 생성된 리소스를 다시 읽어올 수 있는지 확인합니다.
6. 스트리밍 (Streaming) (적용 가능한 경우): SSE 툴을 하나 사용해보고, 시간 초과되는 대신 수집된 이벤트들을 반환하는지 확인합니다.
7. 자격 증명 유출 없음 (No credential leakage): 에이전트에게 설정을 출력하도록 요청합니다. 이때 토큰은 채팅이나 생성된 코드에 절대 노출되어서는 안 됩니다.

Step 5: 적절한 표면(surface) 노출하기

에이전트는 300개 operation을 무작위로 제공하는 것보다, 초점이 맞춰진 툴 카탈로그를 훨씬 더 잘 처리합니다. 다음 세 가지 관행은 선택의 정확성을 유지하게 합니다:

• 청중에 따라 필터링하기(Filter by audience). 에이전트 사용을 위해 태그가 지정된 하위 집합(읽기 작업과 통제된 쓰기 작업)만 노출하고, 파괴적이거나 관리자용 작업은 에이전트 서버에서 완전히 제외합니다.
• 수행하는 기능에 맞춰 툴 이름 짓기. list_invoices, create_subscription, cancel_subscription과 같이 지어야 하며, 단순히 getAll, postData와 같은 이름은 피해야 합니다.
• 언제 사용해야 하는지 설명하는 설명 작성하기.

운영 시 유의사항 (Operating notes)

• 도구 버전 관리. 에이전트 서버를 출시된 명세 개정판(spec revision)에 고정하세요. 도구 이름이나 인수를 변경하면 저장된 에이전트 워크플로우가 깨지며, 이는 SDK가 깨지는 것과 같은 방식으로 발생합니다. 새 개정판을 게시하기 전에 파괴적 변경 차이점(breaking-change diff)을 실행해야 합니다.
• 호출 감사 (Audit calls). 어떤 에이전트(사용자, 프로젝트)가 어떤 도구를 호출했는지 기록하세요. 에이전트는 기계 속도로 실수를 하므로 호출 로그는 디버깅 추적 경로입니다.
• 인간에게 파괴적인 행동 맡기기. 삭제, 계획 변경, 결제와 같은 작업은 클라이언트에서 확인을 요구하거나 아예 에이전트 카탈로그에서 제외되어야 합니다.
• 문서는 인간을 위해 남겨두기. MCP 도구는 사용자가 이미 해당 영역(domain)을 알고 있다고 가정합니다. 신규 팀원은 여전히 렌더링된 문서를 통해 개념을 학습합니다. 둘 다 동일한 명세에서 파생됩니다.

이 설정을 사용하면 에이전트를 전환하는 것은 통합 프로젝트가 아니라 구성 변경일 뿐입니다. API 지식은 프롬프트 기록에 있는 것이 아니라 계약(contract) 안에 존재합니다. Powerduck은 워크스페이스에서 열린 명세로부터 로컬 MCP 엔드포인트를 제공하고, Cloud에서 버전 관리가 적용된 호스팅, 토큰 범위 엔드포인트를 게시합니다. 데모는 샘플 문서에 대한 서비스 동작을 보여줍니다.

다음으로 읽어볼 것: MCP 대 함수 호출 대 플러그인은 계층 구조를 명확히 하며, AI 코딩 에이전트의 API 문서 붙여넣기 중단하기는 왜 산문 형태의 컨텍스트가 소실되는 반면 타이핑된 도구(typed tools)는 그렇지 않은지 다룹니다.