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

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

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

시작하기 전에

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

구성 검증

OpenAPI 사양을 업로드하면 API Gateway는 MCP 구성에 대해 다음 검증을 수행합니다.

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

인증 모델

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

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

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

참고: MCP 도구로 사용할 수 있도록 작업에 백엔드가 구성되어 있는지 확인하세요 (작업 수준에서 x-google-backend를 사용하거나 전역 기본값을 사용).

전역적으로 사용 설정하면 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를 설정하여 전역적으로 사용 설정된 경우 작업을 선택 해제할 수도 있습니다.

3. tools/list 인증(권장)

기본적으로 사용 가능한 도구를 열거하는 tools/list 메서드는 인증되지 않습니다. 보안 권장사항에 따라 x-google-api-management.mcp에서 tools-list.security를 구성하여 인증을 시행하는 것이 좋습니다. JWT 스키마 또는 API 키 스키마의 이름을 지정할 수 있습니다.

다음 예시에는 JWT가 필요합니다.

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

다음 예시에는 API 키가 필요합니다. 클라이언트는 x-api-key HTTP 헤더에 키를 전송해야 합니다. tools/list는 쿼리 매개변수에서 API 키를 읽지 않습니다. 유효한 키가 없는 요청은 JSON-RPC 오류를 수신하고 도구 목록을 수신하지 않습니다. API 키를 만드는 방법은 API 키 사용을 참조하세요.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

참고: mcp 확장 프로그램을 객체로 구성하면 (예: tools/list에 인증 사용 설정) 모든 적격 작업에 대해 MCP가 전역적으로 사용 설정됩니다. tools/list 보안을 구성하되 모든 적격 작업을 노출하지 않으려면 x-google-mcp-tool: false를 설정하여 해당 작업을 명시적으로 선택 해제해야 합니다.

4. API 구성 만들기 및 배포

주석이 추가된 사양에서 API 구성을 만들고 표준 흐름을 사용하여 게이트웨이에 배포합니다. 자세한 내용은 게이트웨이에 API 배포를 참조하세요. 나중에 도구를 변경하려면 노출된 MCP 도구 업데이트를 참고하세요.

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"}
  }
}'

참고: 클라이언트는 초기화 후 모든 요청에 MCP-Protocol-Version 헤더를 전송해야 합니다. 헤더가 없으면 게이트웨이가 2025-03-26 버전으로 대체됩니다.

핸드셰이크 확인

초기화를 확인합니다. 게이트웨이가 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"}'

도구 탐색

사용 가능한 도구를 나열합니다. tools-list.security를 구성한 경우 JWT의 Authorization: Bearer 헤더 또는 API 키의 x-api-key 헤더와 같은 일치하는 사용자 인증 정보를 추가합니다.

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 헤더로 삽입합니다.

참고: 매개변수를 예약된 시스템 헤더 또는 x-google-로 시작하는 헤더에 바인딩할 수 없습니다.

트랜스코딩된 백엔드 요청은 백엔드 서비스에 대한 직접 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 Gateway의 API 구성은 변경할 수 없으므로 기존 API 구성에서 API 정의를 변경할 수 없습니다. 따라서 tools/list 응답은 배포된 각 API 구성에 대해 정적입니다.

노출된 MCP 도구 또는 tools/list 보안 설정을 추가, 삭제, 이름 변경 또는 업데이트하려면 새 API 구성을 만들고 게이트웨이에 배포합니다.

1. 작업, operationId 값, 요약, 매개변수, x-google-api-management.mcp 및 x-google-mcp-tool 확장 프로그램을 포함하여 OpenAPI 3.x 사양을 업데이트합니다.

2. 새 API 구성 ID로 새 API 구성을 만듭니다.

   gcloud api-gateway api-configs create NEW_CONFIG_ID \
       --api=API_ID \
       --openapi-spec=API_DEFINITION \
       --project=PROJECT_ID \
       --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   다음을 바꿉니다.

   • NEW_CONFIG_ID: 업데이트된 API 구성의 새 ID
   • API_ID: API Gateway API의 ID
   • API_DEFINITION: 업데이트된 OpenAPI 3.x 사양의 경로
   • PROJECT_ID: Google Cloud 프로젝트 ID
   • SERVICE_ACCOUNT_EMAIL: 구성된 인증으로 백엔드의 토큰을 서명하는 데 사용되는 서비스 계정의 이메일 주소입니다. 백엔드에 인증이 필요하지 않으면 이 플래그를 생략합니다.

   자세한 내용은 API 구성 만들기를 참조하세요.

3. 새 API 구성을 사용하도록 API를 제공하는 각 게이트웨이를 업데이트합니다.

   gcloud api-gateway gateways update GATEWAY_ID \
       --api=API_ID \
       --api-config=NEW_CONFIG_ID \
       --location=GCP_REGION \
       --project=PROJECT_ID

   다음을 바꿉니다.

   • GATEWAY_ID: 업데이트할 게이트웨이의 ID
   • GCP_REGION: 게이트웨이가 배포된 리전

   자세한 내용은 게이트웨이 업데이트를 참조하세요.

4. tools/list를 호출하여 업데이트된 도구 세트를 확인합니다. 요청 예시는 도구 탐색을 참고하세요.

5. 이전 API 구성을 사용하는 게이트웨이가 없으면 대체된 API 구성을 삭제합니다.

   gcloud api-gateway api-configs delete OLD_CONFIG_ID \
       --api=API_ID \
       --project=PROJECT_ID

   OLD_CONFIG_ID를 대체된 API 구성의 ID로 바꿉니다. 게이트웨이에서 아직 사용 중인 API 구성은 삭제하지 마세요. 새 API 구성에서 할당량 측정항목의 이름을 바꾸거나 삭제하는 경우 이전 API 구성을 계속 제공하는 게이트웨이는 업데이트될 때까지 HTTP 500 오류를 반환할 수 있습니다(할당량은 전체 API에 적용됨 참조). 자세한 내용은 API 구성 삭제를 참조하세요.

MCP 도구를 업데이트할 때는 다음 출시 및 클라이언트 동작에 유의하세요.

• 다운타임 없는 출시: API Gateway는 다운타임 없이 게이트웨이를 업데이트합니다. 새 API 구성이 전파되는 동안 일부 요청이 이전 API 구성에 잠시 도달할 수 있습니다. API가 여러 게이트웨이 또는 리전에 배포된 경우 각 게이트웨이를 개별적으로 업데이트합니다.
• 클라이언트 도구 캐시: API Gateway는 스테이트리스(Stateless) HTTP 전송을 통해 MCP를 제공하므로 게이트웨이는 notifications/tools/list_changed 알림을 내보내지 않습니다. 게이트웨이 업데이트가 완료되면 도구 정의를 캐시하는 MCP 클라이언트가 tools/list를 다시 호출하여 업데이트된 도구를 검색해야 합니다.
• API 구성 한도: 각 API는 API 구성 100개로 제한되므로 게이트웨이를 업데이트한 후 대체된 API 구성을 삭제하세요. API 구성을 한 번에 하나씩 만듭니다. 첫 번째 API 구성이 완료되기 전에 동일한 API에 대해 두 번째 API 구성을 시작하면 게이트웨이에서 하나 또는 둘 다 사용하지 못할 수 있습니다. 자세한 내용은 할당량 및 제한을 참조하세요.

관측 가능성

MCP 요청은 표준 API Gateway 측정항목 및 로그를 생성합니다. 요청 경로 (일반적으로 /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을 생략하거나 문자열이 아닙니다.
알 수 없는 도구	-32602	200	배포된 API 구성에서 도구 이름을 찾을 수 없습니다. 클라이언트 도구 캐시를 새로고침하거나 노출된 MCP 도구 업데이트를 참고하세요.
잘못된 도구 인수	-32602	200	인수가 누락되었거나 잘못되었습니다. body 키 중첩을 확인합니다.
본문이 너무 큼	-32000	200	응답 페이로드가 크기 한도를 초과했습니다.
전송 본문이 너무 큼	해당 사항 없음	413	원시 HTTP 요청 본문이 게이트웨이 전송 한도를 초과했습니다.
서버 오류	-32000	200	파싱할 수 없는 백엔드 응답입니다. 로그를 확인합니다.
승인되지 않음/금지됨	해당 사항 없음	401/403	인증하지 못했습니다. 응답에는 보호된 리소스 메타데이터를 가리키는 WWW-Authenticate 헤더가 포함됩니다.

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

다음 단계

• 모델 컨텍스트 프로토콜 개요
• OpenAPI 3.x 확장 프로그램
• OpenAPI 3.x 기능 제한사항