Cursor Composer 2.5로 API 구축하는 방법

Cursor Composer 2.5는 에이전트가 전체 API 클라이언트와 라우트 핸들러를 작성할 수 있을 만큼 빠르고 저렴합니다. 문제는 코드가 실제 서비스에 닿는 순간 발생합니다. 모델은 /v2/orders로 깔끔하게 보이는 요청을 작성하지만, 실제 서비스는 /orders를 노출하고 다른 페이로드를 예상합니다. 코드는 컴파일되지만, 작동하지 않으며 이 사실을 세 개의 파일을 더 확인하고 나서야 알게 됩니다.

이 가이드에서는 이러한 문제를 해결하는 워크플로우를 보여줍니다. Composer 2.5를 MCP를 통해 실제 API 사양에 연결하고, 실제 계약에 따라 코드를 생성하게 한 다음, 팀원에게 전달하기 전에 Apidog에서 결과를 확인하는 방법입니다. 이 모델에 익숙하지 않다면, Cursor Composer 2.5 가이드에서 이 모델이 무엇이고 어떻게 접근하는지 다룹니다.

button

에이전트 모델이 API 형태를 추측하는 이유

Composer 2.5는 길고 여러 단계를 거치는 에이전트 작업을 위해 만들어졌습니다. "빌링 서비스용 클라이언트를 추가하고 결제 흐름에 연결해 줘"라고 요청하면, 계획을 세우고 여러 파일을 편집하며 테스트가 통과할 때까지 실행합니다. 이것이 Composer 2에 비해 향상된 점이며, 진정으로 유용합니다.

약점은 버그가 아니라 구조적인 것입니다. 모델이 API 계약의 맥락을 가지고 있지 않을 때, 가장 통계적으로 가능성이 높은 형태로 그 간극을 채웁니다. 즉, 일반적인 필드 이름, REST 규칙, 학습 중에 가장 많이 본 버전 접두사 등을 사용합니다. 결과물은 올바르게 보이고, 린트를 통과합니다. 하지만 서버가 인터넷상의 모든 API의 평균이 아니기 때문에 서버에 대해 실패합니다.

이것의 세 가지 증상은 다음과 같습니다:

거의 일치하는 엔드포인트 (/api/users/{id} vs 당신의 /users/{userId}).
요청 본문에 없던 필드가 생성되거나 잘못된 필드.
서비스의 실제 스키마 대신 일반적인 방식으로 인증 처리.

프롬프트를 통해 일부를 해결할 수 있지만, 전체 OpenAPI 파일을 채팅에 붙여넣는 것은 불안정하고 맥락을 소모합니다. 영구적인 해결책은 모델에 사양에 대한 구조화된 접근 권한을 부여하는 것입니다.

해결책: MCP를 통해 Composer 2.5를 실제 API 사양에 기반을 두기

MCP(Model Context Protocol)는 AI 모델에 도구와 데이터를 제공하기 위한 개방형 표준입니다. Cursor는 MCP 서버를 지원하며, Apidog MCP 서버는 Apidog API 사양을 코드를 작성하는 동안 쿼리할 수 있는 구조화된 소스로 모델에 노출합니다.

실제적인 차이점은 다음과 같습니다. Composer 2.5는 추측하는 대신 실제 엔드포인트, 스키마, 매개변수 및 응답 형태를 읽은 다음, 그에 따라 코드를 작성합니다. 이는 Apidog MCP 서버를 사용한 바이브 코딩의 배경이 되는 아이디어와 동일하며, 이제 전체 작업을 수행할 수 있을 만큼 강력해진 모델에 적용됩니다.

1단계: Apidog에서 API 사양 준비

API 계약은 모델이 읽을 수 있는 어딘가에 존재해야 합니다. Apidog에서 API를 설계하거나 가져와 스키마, 엔드포인트 및 예시가 최신 상태인지 확인하세요. 기존 문서에서 시작하는 경우 Apidog는 OpenAPI 및 Postman 컬렉션을 직접 가져옵니다. 사양은 모델이 따를 진리의 원천이므로, 정확하게 유지하는 것이 전체 게임입니다.

2단계: Apidog MCP 서버를 Cursor에 연결

Cursor는 프로젝트의 구성 파일(일반적으로 .cursor/mcp.json)에서 MCP 서버를 읽습니다. Apidog MCP 서버는 npx를 통해 실행되며 프로젝트를 가리킵니다. 일반적인 구성은 다음과 같습니다:

{
  "mcpServers": {
    "apidog-api-spec": {
      "command": "npx",
      "args": ["-y", "apidog-mcp-server@latest", "--project=<your-project-id>"],
      "env": { "APIDOG_ACCESS_TOKEN": "<your-access-token>" }
    }
  }
}

이 값들은 계정 및 서버 버전에 따라 다르므로 Apidog MCP 설정 안내서의 정확한 명령, 프로젝트 ID 및 토큰을 사용하세요. 새 서버를 인식하도록 저장 후 Cursor를 다시 시작하세요.

3단계: Composer 2.5가 사양을 볼 수 있는지 확인

에이전트 세션을 열고 모델 선택기에서 composer-2.5를 선택한 다음, 먼저 읽기 전용 질문을 하세요:

"apidog-api-spec MCP 서버를 사용하여 주문 리소스 아래의 엔드포인트를 나열하고 주문 생성에 필요한 필드를 알려줘."

실제 엔드포인트와 필드를 반환한다면 연결이 작동하는 것입니다. 일반적인 지식에서 답변한다면 서버가 연결되지 않은 것이므로, 구성을 다시 확인하고 재시작하세요.

4단계: 계약에 따라 구축하도록 하기

이제 실제 작업을 주고 사양을 명시적으로 지정하세요:

"apidog-api-spec 서버를 진리의 원천으로 사용하여, 주문 API를 위한 타입스크립트 클라이언트를 작성해줘. create-order 및 get-order 호출을 포함하고, 요청 및 응답 스키마를 정확히 일치시켜줘. 사양에 정의된 422 유효성 검사 응답에 대한 오류 처리도 추가해줘."

Composer 2.5는 긴 작업을 잘 처리하므로, 여러 파일에 걸쳐 이 작업을 수행하고 계약의 일관성을 유지할 수 있습니다. 프롬프트에서 MCP 소스를 명시하면 가정을 재확인하는 대신 계약에 고정됩니다.

신뢰하기 전에 검증: Apidog 테스트 루프

모델에 기반을 두는 것은 환각을 급격히 줄입니다. 하지만 검증이 선택 사항이 되는 것은 아닙니다. 사양이 실행 중인 서비스보다 약간 뒤처질 수 있으며, 모델이 여전히 엣지 케이스를 잘못 해석할 수 있습니다.

루프를 닫으세요:

생성된 호출을 실제 요청으로 전송합니다. Composer 2.5가 작성한 엔드포인트를 가져와 Apidog에서 실제 또는 모의 환경에 대해 실행합니다. 상태 코드, 응답 본문, 인증이 코드에서 가정한 대로 작동하는지 확인합니다.
작동하는 호출을 테스트로 전환합니다. 검증된 요청을 자동화된 테스트 시나리오로 저장하여 다음 회귀가 사용자가 아닌 CI에 의해 감지되도록 합니다.
아직 구축되지 않은 것을 모의합니다. 모델이 백엔드에서 아직 출시되지 않은 엔드포인트를 위한 클라이언트를 작성했다면, Apidog의 모의 서버는 프런트엔드 작업이 계속되도록 현실적인 응답을 반환합니다. 이는 AI 에이전트와 API 테스트의 패턴과 잘 어울립니다.

원칙: 모델은 계약에 대한 초안을 작성하고, 당신은 초안이 실제 서버에 대해 작동하는지 확인합니다. 에이전트의 속도는 나중에 디버깅에 시간을 낭비하지 않을 때만 복합적으로 작용합니다.

현실적인 엔드 투 엔드 예시

결제 서비스에 환불 기능을 추가한다고 가정해 봅시다.

환불 엔드포인트와 스키마는 이미 디자인 단계에서 Apidog 프로젝트에 존재합니다.
Apidog MCP가 Cursor에 연결되어 있고, Composer 2.5가 선택되어 있습니다.
"apidog-api-spec을 사용하여 환불 클라이언트와 이를 호출하는 React 훅을 빌드해 줘. 사양에서 요구하는 멱등성 키(idempotency-key) 헤더를 포함하여 스키마를 정확히 따르도록 해줘."라고 프롬프트합니다.
Composer 2.5는 실제 계약을 읽고, 클라이언트, 훅 및 타입을 작성하며, 프로젝트의 테스트를 실행합니다.
Apidog를 열고 실제 환불 생성 요청을 보내 멱등성 동작과 중복 시 409 오류를 확인한 다음, 둘 다 테스트 시나리오로 저장합니다.

피한 시나리오: 멱등성 헤더를 잊어버린 클라이언트가 배포되어 스테이징 환경에서 고객에게 두 번 환불하는 사고. 이것이 기반 마련과 검증을 통해 제거되는 버그의 종류입니다.

자주 묻는 질문

Composer 2.5는 MCP를 지원하나요? 네. MCP 서버를 포함하여 Cursor의 모든 에이전트 도구 세트에 접근할 수 있습니다. 모델 선택기에서 선택하고 프로젝트에서 서버를 구성하세요. Composer 2.5 가이드는 모델 선택에 대해 다룹니다.

Composer 2.5와 함께 MCP를 사용하려면 Apidog가 필요한가요? 구조화된 사양 소스가 필요합니다. Apidog MCP 서버는 동일한 장소에서 테스트 및 모킹을 제공하므로 여기서 다루는 경로입니다. Cursor를 위한 최고의 MCP 서버 총정리에 다른 옵션이 있습니다.

모델을 사양에 기반을 두면 모든 환각이 멈출까요? 모델이 추측하는 대신 실제 계약을 읽으므로 가장 큰 범주인 잘못된 엔드포인트와 스키마를 제거합니다. 하지만 테스트를 대체하지는 않습니다. 사양은 실행 중인 서비스와 달라질 수 있으므로 여전히 검증해야 합니다.

작은 프로젝트에도 이것이 가치가 있나요? 모델이 실제 API에 닿는다면 그렇습니다. 설정은 한 번의 구성 파일 작업입니다. 그 보상은 그럴듯한 추측 대신 생성된 모든 호출이 계약과 일치하는 것입니다.

결론

Composer 2.5는 에이전트가 실제 API 작업을 수행하게 할 만큼 빠르고 저렴합니다. 이는 모델이 추측된 평균값 대신 실제 계약에 따라 코드를 작성할 때만 효과가 있습니다. Apidog MCP 서버를 통해 사양을 연결하여 Composer 2.5가 진실을 읽게 하고, Apidog 다운로드를 통해 실시간 요청을 보내고, 응답을 확인하며, 작동하는 호출을 자동화된 테스트 및 모의 환경에 고정하세요. 기반이 다져진 생성과 검증은 에이전트의 속도를 실제 배포 기능으로 전환하는 워크플로우입니다.