모델 컨텍스트 프로토콜 구성

이 문서에서는 원격 모델 컨텍스트 프로토콜 (MCP) 서버 역할을 하도록 API Gateway를 구성하는 방법을 설명합니다.

시작하기 전에

  • API에 유효한 OpenAPI 3.x 사양이 있는지 확인합니다. OpenAPI 2.0에는 MCP가 지원되지 않습니다.
  • API Gateway의 기본사항을 이해해야 합니다.

구성 검증

OpenAPI 사양을 업로드하면 API 게이트웨이에서 MCP 구성에 대해 다음 유효성 검사를 실행합니다.

  • 위치: x-google-mcp-tool 확장 프로그램은 개별 작업 수준에서만 지정해야 합니다.
  • HTTP 메서드: GET, POST, PUT, PATCH, DELETE 작업만 MCP 도구로 노출할 수 있습니다.
  • 도구 이름: 도구 이름은 [A-Za-z0-9_.-]{1,128}와 일치해야 하며 사양 전체에서 고유해야 합니다.
  • 설명: 모든 도구는 비어 있지 않은 설명 (작업의 설명, 요약 또는 재정의에서 가져옴)으로 확인되어야 합니다. 해결 가능한 설명이 없는 작업은 거부됩니다.
  • 보안: tools/list의 인증을 구성하는 경우 components.securitySchemes 아래에 정의된 JWT 보안 스키마를 정확히 하나만 지정해야 합니다. 공개 미리보기에서는 tools/list에 API 키 보안이 지원되지 않습니다.

인증 모델

API Gateway는 호출된 MCP 메서드에 따라 다른 인증 규칙을 적용합니다.

  • 프로토콜 수명 주기: initialize 및 notifications/initialized 메서드는 인증되지 않았습니다.
  • 도구 호출 (tools/call): OpenAPI 사양에서 기본 작업에 정의된 인증 정책을 재사용합니다. REST 엔드포인트를 직접 호출하는 것과 동일한 API 키 또는 JWT 요구사항이 적용됩니다.
  • 도구 검색 (tools/list): 기본적으로 이 메서드는 인증되지 않습니다. 하지만 보안 권장사항에 따라 tools-list.security를 사용하여 이 메서드의 인증을 사용 설정하여 도구 검색을 보호하는 것이 좋습니다. 인증을 사용 설정하려면 JWT 보안 스키마를 사용해야 합니다. tools/list에는 API 키 인증이 지원되지 않습니다.

MCP 구성 단계

API를 MCP 도구로 노출하려면 다음 단계를 따르세요.

1. 노출할 작업 식별

OpenAPI 사양을 검토하고 AI 에이전트가 사용할 수 있어야 하는 작업을 결정합니다.

2. OpenAPI 사양 업데이트

적격한 모든 작업에 대해 MCP를 전역적으로 사용 설정하거나 작업별로 구성할 수 있습니다.

글로벌 지원

문서 수준에서 x-google-api-management에 mcp 필드를 추가하여 MCP를 전역적으로 사용 설정합니다.

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

전역으로 사용 설정하면 HTTP 메서드와 경로를 기반으로 적격한 모든 작업이 MCP 도구로 노출됩니다. 기본적으로 도구 이름은 작업의 operationId이고 설명은 작업의 설명 또는 요약입니다.

작업별 구성

x-google-mcp-tool를 사용하여 전역 설정을 재정의하거나 작업을 선택적으로 노출할 수 있습니다.

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

x-google-mcp-tool: false를 설정하여 전역으로 사용 설정된 경우 작업을 선택 해제할 수도 있습니다.

기본적으로 사용 가능한 도구를 열거하는 tools/list 메서드는 인증되지 않습니다. 보안 권장사항에 따라 x-google-api-management/mcp 아래에 tools-list.security를 구성하여 인증을 적용하는 것이 좋습니다. JWT 스키마를 사용해야 합니다. API 키는 이 메서드에서 지원되지 않습니다.

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

4. API 구성 만들기 및 배포

주석이 추가된 사양에서 API 구성을 만들고 표준 흐름을 사용하여 게이트웨이에 배포합니다. 자세한 내용은 게이트웨이에 API 배포를 참고하세요.

5. MCP 지원 확인

배포 후 게이트웨이가 MCP 요청을 처리하는지 확인할 수 있습니다.

핸드셰이크

프로토콜 버전과 기능을 설정하기 위해 초기화 요청을 전송합니다.

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

핸드셰이크 확인

초기화를 확인합니다. 게이트웨이는 HTTP 202 Accepted로 응답합니다.

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

도구 탐색

사용 가능한 도구를 나열합니다.

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

인수가 REST 요청에 매핑되는 방식

도구에 전달된 인수는 OpenAPI 사양에 따라 기본 REST 요청에 매핑됩니다.

  • 경로 및 쿼리 매개변수: OpenAPI 매개변수 이름으로 키가 지정된 arguments 객체의 최상위 속성이 됩니다.
  • 요청 본문: body라는 단일 속성 아래에 중첩됩니다. 예를 들어 리소스를 만들려면 {"body": {"fieldName": "value"}}를 전달합니다.
  • 헤더: 최상위 속성이 됩니다. 게이트웨이는 백엔드 호출에 표준 HTTP 헤더로 삽입합니다.

트랜스코딩된 백엔드 요청은 백엔드 서비스에 대한 직접 REST 요청과 구별할 수 없습니다. 백엔드 서비스는 직접 REST 호출과 MCP에서 트랜스코딩된 호출을 프로그래매틱 방식으로 구분할 수 없습니다.

도구 호출

특정 도구를 호출합니다. 기본 REST 작업에 필요한 경우 필수 인증 토큰을 포함해야 합니다.

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

관측 가능성

MCP 요청은 표준 API 게이트웨이 측정항목과 로그를 생성합니다. 요청 경로 (일반적으로 /mcp로 끝남)를 검사하거나 맞춤 측정항목을 구성하여 MCP 트래픽을 표준 REST 트래픽과 구분할 수 있습니다.

MCP 오류 문제 해결

MCP는 전송 실패와 프로토콜 실패를 구분합니다. 게이트웨이는 프로토콜 및 애플리케이션 오류에 대해 JSON-RPC 오류 객체와 함께 HTTP 200을 반환합니다. 200이 아닌 응답은 많은 MCP 클라이언트가 전송 계층에서 실패할 수 있기 때문입니다.

다음 표에는 일반적인 증상과 해결 방법이 나와 있습니다.

증상 JSON-RPC 코드 HTTP 상태 의미 및 일반적인 해결 방법
사용할 수 없는 방식 해당 사항 없음 405 POST가 아닌 요청이 /mcp에 도달했습니다. HTTP POST만 지원됩니다.
JSON 파싱 오류 -32700 400 요청 본문이 유효한 JSON이 아닙니다.
메서드 또는 ID가 누락되었거나 잘못됨 -32600 200 본문이 유효한 JSON이지만 유효한 JSON-RPC 요청이 아닙니다. 필수 입력란 (jsonrpc, method, id)을 확인합니다.
메서드가 지원되지 않음 -32601 200 메서드가 지원되는 범위를 벗어납니다 (예: ping).
지원되지 않는 프로토콜 버전 -32602 200 protocolVersion는 게이트웨이에서 지원하지 않는 버전을 지정합니다.
프로토콜 버전 누락 -32602 200 initialize 매개변수에서 protocolVersion이 누락되었거나 protocolVersion이 문자열이 아닙니다.
알 수 없는 도구 -32602 200 도구 이름을 찾을 수 없습니다. 클라이언트 캐시를 정리하거나 배포를 확인합니다.
잘못된 도구 인수 -32602 200 인수가 누락되었거나 잘못되었습니다. body 키 중첩을 확인합니다.
본문이 너무 큼 -32000 200 응답 페이로드가 크기 한도를 초과했습니다.
전송 본문이 너무 큼 해당 사항 없음 413 원시 HTTP 요청 본문이 게이트웨이 전송 한도를 초과했습니다.
서버 오류 -32000 200 파싱할 수 없는 백엔드 응답입니다. 로그를 확인합니다.
승인되지 않음 / 금지됨 해당 사항 없음 401/403 인증하지 못했습니다. 응답에는 보호된 리소스 메타데이터를 가리키는 WWW-Authenticate 헤더가 포함됩니다.

백엔드 애플리케이션 오류는 일반적으로 백엔드 오류 본문이 포함된 result.isError: true이 있는 성공적인 JSON-RPC 응답 (HTTP 200)으로 표시됩니다.

다음 단계