들어가며: MCP 서버를 또 만들어야 한다는 부담

AI 에이전트를 실무에 붙이다 보면 결국 사내 REST API를 도구로 노출해야 하는 순간이 옵니다. 그런데 기존 방식은 생각보다 번거로워요. 에이전트가 쓸 수 있게 하려고 별도의 MCP 서버를 세우고, 게이트웨이가 이미 처리하던 라우팅·인증·쿼터 로직을 그 서버에 다시 구현해야 했습니다. 관리 포인트만 늘어나는 셈이죠.

Google Cloud API Gateway가 이 부분을 정리했습니다. 이미 배포 중인 OpenAPI 스펙에 MCP 관련 어노테이션만 달면, 게이트웨이 자체가 원격 MCP 서버로 동작합니다. 새로 호스팅할 서버도, 유지보수할 코드도 없어요. 현재 Public Preview 단계이고, REST·OpenAPI 3.x 백엔드를 기존 인증 체계 그대로 지원합니다.

이 글에서는 실제로 스펙을 수정하고, 배포하고, ADK 에이전트에 연결하는 흐름을 순서대로 짚어볼게요. 삽질 없이 바로 적용할 수 있게 정리했습니다.

참고로 이 기능의 공식 발표 내용은 근거자료에서 확인할 수 있어요.

Google Cloud API Gateway architecture diagram connecting REST APIs to AI agents via MCP protocol IT Technology Image

핵심 구현: OpenAPI 스펙에 MCP 주석 달기

1단계. 스펙에 MCP 활성화 선언

기존 OpenAPI 스펙 상단에 x-google-api-management.mcp: true를 추가하면 해당 스펙의 모든 오퍼레이션이 MCP 도구 후보가 됩니다. 백엔드 주소도 함께 지정해 주세요.

openapi: 3.0.4
info:
  title: Order Service
  version: 1.0.0
x-google-api-management:
  mcp: true  # 이 스펙의 오퍼레이션을 MCP 도구로 노출
  backends:
    orders-backend:
      address: https://orders-a1b2c3-uc.a.run.app
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      description: Returns the current status, carrier, and ETA for an order.
      x-google-backend: orders-backend
      x-google-mcp-tool:
        name: get_order_status
        description: "Look up the delivery status and ETA of a customer order.
          Use this when the user asks where an order is or when it will arrive."
        parameters:
          - name: orderId
            in: path
            required: true
            schema:
              type: string

여기서 중요한 포인트는 description 작성 방식입니다. LLM은 도구 설명을 보고 호출 여부를 판단하기 때문에, "무엇을 반환하는지"보다 "언제, 왜 이 도구를 써야 하는지"를 적어야 합니다. 위 예시처럼 사용자 질문 시나리오를 그대로 넣는 게 좋아요.

2단계. 게이트웨이 배포

평소 API config 배포하듯 그대로 배포하면 됩니다. API Gateway가 MCP 인식 설정을 자동 생성하고 /mcp 베이스 경로로 서빙을 시작합니다. 추가 인프라 프로비저닝은 없습니다.

3단계. 도구 검색 권한 제어

기본값으로 tools/list는 인증 없이 열려 있습니다. 개발 중에는 편하지만, 운영에서는 도구 이름과 입력 스키마가 그대로 공개된다는 점을 주의해야 합니다. 운영 환경에서는 JWT를 요구하세요. API 키로는 이 메서드를 보호할 수 없습니다.

x-google-api-management:
  mcp:
    tools-list:
      security:
        orderServiceJwt: []  # 객체 형태로 쓰면 MCP 전체 활성화

tools/call은 설정과 무관하게 항상 기존 REST 오퍼레이션의 인증을 강제합니다. 검색은 막고 호출은 허용하는 구조가 기본이라는 뜻이죠.

4단계. ADK 에이전트에 연결

이제 MCP 클라이언트를 게이트웨이의 /mcp 엔드포인트로 향하게 하면 됩니다. ADK에서는 McpToolset에 게이트웨이가 기대하는 자격 증명을 함께 넘기면 끝입니다.

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams

order_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/mcp",
        headers={"x-api-key": API_KEY},
    )
)

agent = Agent(
    model="gemini-2.5-flash",
    name="order_support_agent",
    instruction="Help the user check on their orders.",
    tools=[order_tools],
)

게이트웨이는 도구 인자를 REST의 path·query·body·header로 매핑하고, 기존 정책을 그대로 태운 뒤 응답을 MCP 결과로 변환합니다. 실제 와이어에서 어떻게 보이는지 확인하려면 다음처럼 호출해 보세요.

curl -X POST "https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/mcp" \
  -H "content-type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}'

응답은 JSON-RPC 형식으로 돌아옵니다.

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text",
"text":"{\"orderId\":\"A-1042\",\"status\":\"IN_TRANSIT\",\"eta\":\"2026-09-24\"}"}],
"isError":false}}

MCP 트래픽과 REST 트래픽이 동일한 정책 경로를 공유한다는 점이 이 구조의 핵심입니다. 인증, 쿼터, 로깅을 MCP용으로 따로 만들 필요가 없어요.

Developer deploying OpenAPI spec with x-google-mcp-tool annotations on Google Cloud console Technical Structure Concept

주의사항과 한계: 지금 바로 못 쓰는 것들

Public Preview 단계라 커버리지에 제약이 있습니다. 실무 투입 전에 반드시 확인해야 할 항목들입니다.

항목현재 상태실무 영향
REST / OpenAPI 3.x 백엔드지원대부분의 사내 API 커버
기존 인증 체계 (JWT, API Key)그대로 재사용마이그레이션 비용 없음
MCP resources / prompts로드맵도구 호출만 우선 지원
응답 스트리밍로드맵장시간 응답은 폴링 필요
Model Armor 페이로드 검사로드맵보안 정책은 별도 설계 필요
HTTP 204 등 빈 바디 응답미노출삭제·상태변경 API는 도구화 불가
깊은 중첩 객체 스키마tools/list에 일부 미표시복잡한 요청 모델은 단순화 권장
게이트웨이당 도구 수최대 1,000개대규모 API는 분할 배포 고려
MCP + 모델 라우팅 동시 활성화불가같은 API config에서 함께 못 씀

특히 빈 바디 응답(204)이 노출되지 않는 점은 의외로 발목을 잡습니다. "주문 취소", "상태 변경" 같은 액션성 API는 응답 바디가 없는 경우가 많거든요. 이런 오퍼레이션은 별도 래퍼를 두거나 응답에 확인 메시지를 담는 형태로 우회해야 합니다.

또 하나, tools/list를 인증 없이 열어두면 도구 이름과 입력 스키마가 그대로 노출됩니다. 내부 API 구조를 외부에 알려주는 셈이니, 운영 배포 시에는 반드시 JWT 보안 설정을 챙기세요.

한국 개발 생태계에서의 적용 맥락

국내 SI·엔터프라이즈 환경에서는 API 게이트웨이가 이미 사내 표준으로 자리 잡은 경우가 많습니다. 이 기능의 진짜 장점은 기존 게이트웨이 정책을 그대로 재사용한다는 점이에요. 별도 MCP 서버를 세우면 보안팀·인프라팀과 다시 협의해야 하지만, 이 방식은 이미 승인된 인증·쿼터 체계를 그대로 태우기 때문에 조직 내 승인 절차가 훨씬 짧습니다.

다만 Cloud Run 기반이 아닌 온프레미스 백엔드나 사내 방화벽 뒤에 있는 서비스는 별도 검토가 필요합니다. API Gateway가 퍼블릭 엔드포인트로 나가는 구조이기 때문에, 내부망 전용 API를 그대로 노출하면 안 되고 VPC 라우팅 설계를 먼저 확인해야 해요.

AI agent using McpToolset in ADK to call order status REST API through gateway Development Concept Image

마무리: 오늘 바로 첫 도구를 노출해 보세요

정리하면 이렇습니다.

  1. 기존 OpenAPI 스펙에 x-google-api-management.mcp: true 한 줄 추가
  2. 오퍼레이션별로 x-google-mcp-tool로 도구 이름과 설명 지정 (설명은 "언제 쓰는지" 중심으로)
  3. 평소처럼 배포 → /mcp 경로로 자동 서빙
  4. 운영에서는 tools/list에 JWT 보안 필수
  5. ADK의 McpToolset으로 에이전트에 연결

별도 서버를 운영하지 않아도 된다는 점이 가장 큰 변화입니다. 인증·쿼터·로깅이 MCP와 REST에 걸쳐 하나의 정책 경로로 통일되기 때문에, 보안 감사 관점에서도 설명하기 쉬운 구조예요.

다음 단계로는 MCP resources와 prompts가 로드맵에 있으니, 도구 호출 외에 컨텍스트 제공까지 확장될 시점을 지켜보면 좋겠습니다. 그 전까지는 도구 설명을 정교하게 다듬는 데 집중하세요. LLM이 도구를 잘못 고르는 문제의 8할은 설명이 부실해서 생깁니다.

함께 보면 좋은 글

본 콘텐츠는 신뢰할 수 있는 출처를 바탕으로 AI 도구를 활용하여 초안이 작성되었으며, 편집자의 검토를 거쳐 발행되었습니다. 전문가의 조언을 대체하지 않습니다.