모델 컨텍스트 프로토콜 개요

이 문서에서는 API 게이트웨이의 모델 컨텍스트 프로토콜 (MCP) 지원을 간략하게 설명합니다.

API 게이트웨이는 원격 MCP 서버 역할을 할 수 있으므로 백엔드 서비스를 다시 작성하지 않고도 기존 REST API를 AI 에이전트 및 LLM에 노출할 수 있습니다.

배경

모델 컨텍스트 프로토콜 (MCP)은 기존 인프라를 기반으로 직접 AI 에이전트를 빌드할 수 있는 개방형 표준입니다. MCP는 모든 도구 또는 API에 맞춤 통합 코드를 작성하는 대신 AI 모델이 환경에서 기능을 검색하고 호출할 수 있는 표준 방법을 제공합니다.

MCP 서버로 구성된 경우 API Gateway는 프록시 역할을 합니다. 에이전트 시스템에서 전송된 표준 MCP JSON-RPC 프로토콜 메시지를 기존 백엔드를 향한 표준 HTTP REST 요청으로 변환합니다.

지원되는 기능

공개 미리보기 기간 동안 API Gateway는 다음 MCP 기능을 지원합니다.

  • 원격 MCP 서버: API Gateway가 원격 서버 역할을 하며 HTTP (POST)를 통해 MCP 요청을 수신합니다.
  • OpenAPI 3.x 통합: MCP 구성은 맞춤 확장 프로그램을 사용하여 OpenAPI 3.x 사양에서 직접 파생됩니다.
  • 지원되는 MCP 수명 주기 메서드:
    • initialize: 프로토콜 버전과 기능을 설정합니다.
    • notifications/initialized: 핸드셰이크를 승인합니다.
    • tools/list: 클라이언트가 사용 가능한 도구와 스키마를 검색할 수 있도록 지원합니다.
    • tools/call: 클라이언트가 인수를 사용하여 도구를 호출할 수 있도록 허용합니다.

제한사항

API 게이트웨이의 MCP 지원에는 다음 제한사항이 적용됩니다.

  • 리소스 (resources/*) 및 프롬프트 (prompts/*)는 지원되지 않습니다.
  • Stdio 전송은 지원되지 않습니다.
  • OpenAPI 2.0은 지원되지 않습니다.
  • 스트리밍 또는 장기 실행 도구 호출은 지원되지 않습니다.
  • 모델 라우팅 상호 배타: 동일한 API 구성 내에서 MCP와 모델 라우팅을 모두 사용 설정할 수 없습니다. x-google-api-management.mcp이 사용 설정된 경우 x-google-model-router를 사용할 수 없습니다.

기술적 제한사항의 전체 목록은 OpenAPI 3.x 기능 제한사항을 참고하세요.

사용 사례

  • 기존 REST API를 MCP 도구로 노출: 백엔드 코드를 변경하지 않고 기존 API를 AI 지원 도구로 전환합니다.
  • 작업별 도구 선택: 상담사에게 노출할 API 경로와 메서드를 명시적으로 선택합니다.
  • 도구 노출 영역 보호: 기존 API Gateway 보안 정책 (예: API 키 또는 OAuth)을 MCP 엔드포인트에 적용합니다.

요청 흐름

MCP 요청의 표준 경로는 <basepath>/mcp이며, 여기서 <basepath>는 게이트웨이의 URL 또는 x-google-endpoint 구성에서 파생됩니다.

다음 다이어그램은 MCP tools/call 요청의 요청 흐름을 보여줍니다.

  1. MCP 클라이언트 (예: AI 에이전트)가 게이트웨이의 MCP 엔드포인트 (예: 버전 접두사를 사용하는 경우 POST /mcp 또는 POST /v1/mcp)에 JSON-RPC 요청을 전송합니다.
  2. 게이트웨이는 요청을 검증하고 인증을 확인합니다.
  3. 게이트웨이는 페이로드를 검사하여 호출되는 도구를 확인합니다.
  4. 게이트웨이는 API 구성에 정의된 매핑을 기반으로 MCP 페이로드를 표준 HTTP 요청 (경로, 매개변수, 본문)으로 변환합니다.
  5. 게이트웨이가 백엔드 서비스로 요청을 전달합니다.
  6. 백엔드는 표준 HTTP 응답을 반환합니다.
  7. 게이트웨이는 HTTP 응답을 다시 MCP JSON-RPC 응답으로 변환하여 클라이언트에 반환합니다.

API 허브 및 Agent Registry를 통한 검색

게이트웨이를 API 허브와 통합하면 MCP 지원 게이트웨이가 추가 MCP 관련 메타데이터가 있는 MCP 서버로 API 허브에 게시되며 Agent Registry에도 자동으로 표시됩니다.

MCP가 사용 설정되지 않은 게이트웨이의 경우 표준 API 메타데이터가 게시됩니다. MCP가 사용 설정된 게이트웨이만 API 허브에 이러한 추가 MCP 구성이 표시됩니다.

별도의 등록 단계가 필요하지 않습니다. 그러면 에이전트가 카탈로그를 통해 서버와 도구를 검색할 수 있습니다.

Agent Registry를 쿼리하려면 프로젝트에서 API를 사용 설정하세요.

gcloud services enable agentregistry.googleapis.com

다음 단계