API 문서를 AI 코딩 에이전트에게 붙여넣지 마세요: MCP를 통해 명세(spec)를 제공하세요

코딩 에이전트가 API를 사용하는 방식의 구조적 개선

엔지니어가 생소한 API에 코딩 에이전트를 사용하는 모습을 지켜보면, 매 세션마다 같은 의식이 반복되는 것을 볼 수 있습니다. 그들은 문서 URL을 붙여넣고, 다음으로 인증 섹션을 붙여넣고, 예시 응답을 붙여넣은 후, 수정 사항을 추가합니다: "페이지네이션은 페이지가 아니라 커서다", "돈은 정수 센트 단위다", "리스트 래퍼는 data.items이다". 에이전트는 그럴듯한 코드를 작성하지만 첫 실행에서 실패하고, 엔지니어는 또 다른 스크린샷을 넣어줍니다. 손으로 조립된 컨텍스트(context)는 몇 시간 안에 소멸합니다.

여기 구조적인 해결책이 존재하며, 그것은 더 나은 프롬프트가 아닙니다. 팀이 유지 관리하는 OpenAPI 문서에서 생성된 callable tools로서 MCP를 통해 에이전트에게 계약(contract)을 제공하는 것입니다.

왜 산문(prose)은 잘못된 전송 방식인가

문서를 채팅에 덤프하면 사라지지 않는 세 가지 실패 모드가 발생합니다:

1. 오래됨 (Staleness). 붙여넣은 텍스트는 스냅샷일 뿐입니다. 사양(spec)이 지난 스프린트에서 변경되었지만, 에이전트의 컨텍스트는 그렇지 않았고 아무도 경고하지 않습니다.
2. 반복적으로 지불되는 토큰 비용. 모든 대화마다 동일한 40페이지가 재업로드됩니다. 매 턴(turn)마다 파일을 다시 읽는 에이전트는 이 비용을 증폭시킵니다.
3. 강제력 부족 (No enforcement). 산문은 "ids는 data.id 아래의 UUID이다"라고 말하지만, 아무것도 런타임에 실패할 때까지 호출을 검증하지 않기 때문에 에이전트는 어쨌든 resp.id를 작성합니다.

문서 기반의 RAG 파이프라인(RAG pipelines)은 검색(retrieval)을 개선할 뿐, 강제력에는 아무런 도움이 되지 않습니다. 모델은 여전히 평소와 같은 환각 표면(hallucination surface)과 함께 자신이 수행하려는 호출에 대해 설명만 할 뿐입니다.

MCP 구조가 바뀌는 방식

OpenAPI-to-MCP 서버는 각 연산(operation)을 도구(tool)로 변환합니다. 에이전트는 POST /v1/orders라는 것이 존재한다는 것을 읽지 않습니다. 대신, create_order라는 도구를 보게 되며, 이 도구의 inputSchema가 plan_code와 quantity를 요구하고, HTTP 호출 전에 누락된 필드를 거부하며, 파싱된 응답을 반환합니다. 그 차이점은 실질적입니다:

• 디스커버리(Discovery)는 구조화되어 있습니다. 툴 이름과 JSON 스키마는 모델 선택을 위해 구축되었고, 일반적인 설명문은 사람이 빠르게 훑어볼 수 있도록 구축되었습니다.
• 검증(Validation)은 비행 전(pre-flight)에 이루어집니다. 잘못된 타입은 에이전트가 즉시 수정하는 툴 오류일 뿐이며, 엔지니어가 읽어야 하는 스테이징 환경의 422 에러 코드가 아닙니다.
• 인증(Auth)은 중앙 집중식입니다. 토큰은 MCP 서버 설정에 존재하며, 프롬프트나 커밋된 코드에는 절대 포함되지 않습니다.
• 계약(Contract)은 한 곳에서 업데이트됩니다. 새로운 스펙 버전을 배포하면, 해당 엔드포인트에 연결된 모든 에이전트가 재붙여넣기 없이 이를 받게 됩니다.
• 스트리밍 작업(Streaming operations)도 사용 가능합니다. 이벤트 스키마와 함께 문서화된 SSE(Server-Sent Events) 작업은 스트림을 열고 수집된 이벤트를 반환하는 툴이 되며, 에이전트가 마치 스트림이 존재하지 않는 것처럼 행동할 필요가 없습니다.

실제 설정 구조는 다음과 같습니다

로컬 개발에서는 스펙 파일 위에서 로컬 서버를 사용합니다:

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

Point Cursor, Claude Code 또는 모든 MCP 클라이언트를 해당 설정에 연결하면 청구(billing) 작업들이 툴로 나타납니다. 파트너 통합이나 내부 지원 도구와 같은 공유 환경의 경우에도 동일한 스펙이 사용자별 토큰을 가진 호스팅된 MCP 엔드포인트로 게시되며, 에이전트 통합이 스펙 배포에 의해 깨지는 것을 방지하기 위해 버전이 고정됩니다.

토큰 범위 지정(token scoping)은 강조할 가치가 있습니다. 에이전트의 토큰에는 최소한의 동사만 부여해야 합니다: 코드 생성 작업에는 읽기 전용(read-only)으로, 데이터를 생성하는 모든 작업에는 샌드박스 조직에 한정된 쓰기 권한을 주어야 합니다. 카탈로그를 탐색할 수 있는 에이전트가 계정을 삭제할 수 있는 토큰을 보유해서는 안 됩니다.

MCP가 진정으로 강점을 보이는 영역

• 자체 API에 대한 반복적인 통합 작업. 모든 내부 에이전트, 코드 생성(codegen) 작업, 지원 스크립트는 동일한 타입 표면을 갖게 됩니다.
• 작은 연산이 많은 환경. 에이전트는 400페이지짜리 문서 하나보다 수십 개의 좁은 도구를 탐색하는 것이 더 좋습니다.
• 강력한 강제(Enforcement)가 필요한 영역. 청구, 신원 확인, 규정 준수와 같이 잘못된 요청이 비용이 많이 드는 곳에서는 사전 비행 스키마 검증(pre-flight schema validation)만으로도 그 가치를 합니다.
• 빠르게 변화하는 명세(spec). 계약이 매주 변경된다면, 프롬프트에 복사되는 모든 것은 이미 잘못된 것입니다.

적합하지 않은 경우 (Where it does not)

MCP는 문서나 SDK의 만능 대체재가 아니며, 그렇게 판매하면 새로운 문제를 야기합니다:

• 일회성 탐색(One-off exploration). API를 평가하는 개발자는 내러티브 가이드, 개념, 순서화에 대한 안내를 원하지만, 도구는 사용자가 이미 무엇을 하고 있는지 알고 있다고 가정합니다. 렌더링된 문서를 유지하세요.
• 성능이 중요하거나 배치(batch) 클라이언트. 리소스당 도구를 호출하는 에이전트는 괜찮지만, 프로덕션 코드는 연결 풀링(connection pooling), 재시도(retries), 타입 모델을 갖춘 생성된 SDK를 사용해야 합니다. MCP는 에이전트의 작업 루프용이지 배포되는 런타임용이 아닙니다.
• 명세에 없는 연산. MCP는 계약서가 말하는 것만을 노출합니다. 명세 자체가 거짓이라면, 도구도 거짓입니다. OpenAPI 문서는 여전히 유지되어야 하며, 이상적으로는 역공학적 사후 작업(reverse-engineered afterthought)이라기보다는 설계의 원천으로 사용되어야 합니다.
• 거대한 평면 구조. 접두사 없는 300개의 도구는 선택을 저하시킵니다. 청중별로 태그가 지정된 하위 집합을 노출하세요.

노동 분담에 대한 정직한 구분 (The honest division of labor)

2026년의 성숙한 설정은 하나의 OpenAPI 문서를 세 가지 방식으로 렌더링하는 것입니다. 각각은 다른 소비자를 위한 것입니다:

1. API를 학습하는 인간을 위한 렌더링된 문서(Rendered documentation).
2. 프로덕션 코드를 위한 생성된 SDK(Generated SDKs).
3. 통합 및 탐색 작업을 수행하는 에이전트를 위한 MCP 서버(An MCP server).

명세(spec)는 한 번만 유지하고, 나머지 세 가지를 파생시키세요. 피해야 할 실패 모드는 네 개의 팀이 동일한 엔드포인트를 독립적으로 설명하는 경우입니다. 마크다운에 하나, SDK에 하나, MCP 툴 래퍼에 하나, 테스트 고정 장치(test fixtures)에 하나로요. 이것이 바로 계약(contract)이 제거하도록 되어 있던 정확한 중복입니다.

Powerduck은 작업 공간에서 열린 명세로부터 로컬 MCP 엔드포인트를 제공하고, 클라우드에서 접근 제어와 함께 호스팅된 버전을 게시합니다. 데모는 샘플 문서에 대한 서비스 동작을 보여줍니다. 단계별 변환 과정은 OpenAPI 명세를 MCP 서버로 변환하는 방법에서 확인할 수 있습니다.

다음으로 읽어볼 내용: API를 재도입하지 않고 AI 도구를 전환하기는 계약을 특정 공급업체의 에이전트에 종속시키지 않는 것에 관한 것이며, AI가 시스템을 작성할 때 누가 완료를 정의하는가는 검증 측면을 다룹니다.