Google가 REST를 API Gateway MCP에 올린 뒤 발견이 여전히 JSON인 이유: OpenAPI 3.x에서 tools/list까지

결론부터: 게이트웨이가 MCP Server를 대신한다. 발견 계약은 여전히 JSON 문서다.2026년 9월 24일, Google 개발자 블로그는 Cloud API Gateway가 Public Preview에서, 이미 배포한 OpenAPI 3.x 조작을 원격 MCP 도구로 노출한다고 했다 — 따로 짓거나 호스팅할 MCP Server는 없다. 문서는 더 일찍 왔다: 9월 11일 릴리스 노트에 이미 Enable MCP가 있다. 게이트웨이는 /mcp에서 표준 JSON-RPC를 받고, tools/call을 기존 REST 요청으로 트랜스코드하며, JWT, API 키, 할당량, 로그를 한 정책 경로에 둔다. Agent가 보는 것은 「REST가 마법이 됐다」가 아니다. tools/list가 내는 도구 이름과 input schema다 — 여전히 JSON.

이 글은 2026년 9월 30일 기준. 그날에도 유효한 그 블로그와 API Gateway 문서를 따른다. 본 사이트는 이미 MCP란 무엇인가, Skill 발견이 왜 여전히 JSON인가, 악성 JSON과 Tool Calling을 다뤘다. 이 글은 OpenAPI가 게이트웨이에 들어간 뒤 어느 JSON 층을 먼저 보고, 어느 층이 기본으로 열려 있는지만 답한다.

「게이트웨이가 MCP Server」가 실제로 낸 것

공식 한 줄은 짧다: 기업 능력의 대부분은 REST 뒤에 있고, Agent는 보지 못한다. 팀은 보통 MCP Server를 하나 더 세우고 라우팅, 인증, 할당량을 다시 구현한다. API Gateway는 Google Cloud 게이트웨이 라인의 가벼운 입구다. 몇 분 안에 관리하고 Agent에 노출해야 하는 Cloud Run 서비스가 여기를 탄다. 전체 수명주기, 무거운 트래픽 정책, 과금은 Apigee에 남는다. 이런 MCP Server를 포함한 출행 Agent 호출은 Agent Gateway를 탄다. 출행 모델 라우팅은 반대 방향이고, MCP와 API config를 같이 쓸 수 없다.

지원하는 수명주기 메서드는 넷뿐이다: initialize, notifications/initialized, tools/list, tools/call. 나머지(resources/*, prompts/*)는 JSON-RPC -32601을 돌려준다. 전송은 HTTP POST. stdio는 없다. 샘플 헤더는 MCP-Protocol-Version: 2025-11-25. 규격 자체는 2026-07-28에 핸드셰이크를 바꿨다; 이 프리뷰는 2025-11-25에 못 박는다. 버전 문자열조차 JSON 봉투에서 먼저 맞춰야 하는 필드다.

또 하나의 MCP Server를 쓰는 것이 아니다

트랜스코드된 REST 요청은 브라우저나 SDK 호출과 구분이 없다. 할당량은 조작 단위다; MCP와 REST가 한 몫을 나눈다. 백엔드는 Agent용 인터페이스를 하나 더 키우지 않는다. 바뀌는 것은 발견 면이다: 예전에는 사람이 OpenAPI를 읽었다; 이제 모델이 tools/list 안의 JSON Schema를 읽는다.

그러니 「운영할 MCP Server가 없다」는 「유지할 JSON 계약이 없다」가 아니다. 빈 설명, 깊은 객체, 남은 2.0은 발견 면이나 트랜스코드에서 드러난다. MCP란 무엇인가를 보라.

계약은 OpenAPI 3.x에서 자란다

문서에서 MCP를 켜는 것은 x-google-api-management.mcp다. 조작마다 x-google-mcp-tool로 이름을 바꾸고, 설명을 고치거나, false로 빠져나갈 수 있다. 노출할 조작마다 백엔드와 비어 있지 않은 description이 필요하다. GET / POST / PUT / PATCH / DELETE만 된다. 도구 이름은 [A-Za-z0-9_.-]{1,128}에 맞아야 하고, 게이트웨이에서 유일해야 한다.

공식 최소 모양(페이지에는 YAML; 의미는 JSON 객체):

x-google-api-management:
  mcp: true
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      description: Returns the current status, carrier, and ETA for an order.
      x-google-mcp-tool:
        name: get_order_status
        description: "Look up the delivery status and ETA of a customer order."
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string

description은 모델이 「언제 칠지」를 고르는 주 신호다. Google은 무엇이 돌아오는지만이 아니라 when / why를 쓰라고 한다. path, query, body, header schema가 도구 arguments가 된다. 중첩 객체는 tools/list에서 다 펼쳐지지 않을 수 있다 — 문서에 적힌 프리뷰 한도이지, 검증기가 깨진 것이 아니다. 로컬에서 OpenAPI를 평평하게 펼친 뒤, 게이트웨이의 input schema와 Diff하라.

tools/list는 기본이 무인증

기본값으로는 누구나 POST /mcp로 카탈로그를 받을 수 있다: 이름, 설명, input schema. 개발에는 편하다. 생산에서는 파라미터 계약을 공개하는 것이다. Google은 tools/list에 JWT를 권한다. Public Preview에서 API 키는 이 메서드를 지키지 못한다. 객체 형태로 써도 MCP는 전역으로 켜진다; 노출하고 싶지 않은 조작은 x-google-mcp-tool: false가 필요하다.

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

tools/call은 발견 면을 잠갔든 아니든, 항상 아래 REST 인증을 강제한다. 열린 카탈로그와 잠긴 호출은 다른 일이다. 도구 이름과 schema가 민감하면, 올리기 전에 tools/list를 잠가라. 악성 JSON 가이드와 같은 층이다: 모델이 보는 계약이 넓을수록, 주입 면도 넓다.

tools/call은 여전히 JSON-RPC

문서의 온와이어 모양은:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}

게이트웨이는 arguments를 path / query / body / header에 다시 채우고, 정책을 돌린 뒤, 백엔드 응답을 MCP result로 감싼다. 디버깅할 때는 층을 나눠라: 바깥 봉투는 JSON-RPC; 안쪽 페이로드는 업무 JSON. 파싱 실패는 한쪽 층의 것이다. ADK 샘플은 Streamable HTTP를 …/mcp에 대고, 게이트웨이가 이미 기대하는 자격 증명을 그대로 실을 수 있다.

게이트웨이를 API hub에 붙이면, MCP를 켠 config는 MCP 메타데이터와 함께 게시되고 Agent Registry에 나타난다. 디렉터리는 바뀌었다. 필드 계약은 바뀌지 않았다: 여전히 당신 OpenAPI에서 자란 schema다. Skill 발견은 다른 JSON 문서다 — SEP-2640과 skill://index.json을 보라. 두 카탈로그를 한 표로 합치지 마라.

Public Preview에서 먼저 읽을 제한

• OpenAPI 2.0은 지원하지 않는다. 먼저 3.x로 올려라.
• 빈 본문(HTTP 204) 조작은 도구로 노출되지 않는다.
• 깊게 중첩된 객체 schema는 tools/list에서 잘릴 수 있다.
• 게이트웨이 하나는 대략 1,000개 도구까지 낸다.
• MCP와 model routing은 API config 하나를 같이 쓸 수 없다.
• resources / prompts, 응답 스트리밍, Model Armor 검사는 아직 로드맵에 있다.

「나중에 다듬을 경험」이 아니다. 204 조작은 카탈로그에서 사라지고, 모델은 다른 것을 친다. 잘린 schema는 strict 검증기나 실제 백엔드와 맞지 않는다. MCP 2026 마이그레이션 가이드는 프로토콜 버전 이야기다. 이 글이 보태는 것은: 게이트웨이가 만든 list는 리포의 전체 OpenAPI와 같지 않을 수 있다는 점이다.

스위치를 켜기 전에 확인할 JSON 네 장

1. 리포의 OpenAPI 3.x. 2.0은 먼저 올려라. 노출할 조작마다 비어 있지 않은 description, 백엔드, 적법한 도구 이름이 있다.
2. 게이트웨이의 tools/list. input schema가 잘렸는지, 공개하고 싶지 않은 조작이 새어 나왔는지 보라.
3. 실제 tools/call 한 줄. arguments가 REST로 되돌아가는가? 봉투는 JSON-RPC 2.0인가?
4. 발견 면의 security 객체. tools/list가 열린 채로 올리지 마라. JWT scheme 이름은 이미 components.securitySchemes에 있어야 한다.

로컬 JSON 도구로 스펙을 보라

MCP를 켜기 전에, 브라우저에서 텍스트 세 장을 펼쳐라: OpenAPI(YAML은 먼저 JSON으로), tools/list 응답 한 장, tools/call에 보낼 arguments 객체.

• JSON 검증기 — 문법이 적법한가; Schema가 있으면 필수와 여분 키를 같이 검사하라.
• JSON ↔ YAML — 대부분의 OpenAPI는 YAML로 산다; list와 Diff하기 전에 변환하라.
• JSON Diff — 리포의 parameters schema와 게이트웨이가 낸 inputSchema를 비교하라.

데이터는 브라우저를 떠나지 않는다. 계약을 평평하게 본 뒤, 게이트웨이 스위치를 켜라. 게이트웨이가 트랜스코드한다. 필드 이름과 required는 프리뷰의 잘림과 같이 느슨해지면 안 된다.

FAQ

요약

API Gateway가 가져가는 것은 MCP Server 프로세스다. JSON 계약은 가져가지 않는다.OpenAPI 3.x가 tools/list를 키운다. tools/call은 JSON-RPC로 남는다. 정책은 이미 가진 REST 정책이다. 열린 카탈로그, 잘린 중첩 schema, 사라진 204 조작은 출시 전 점검이다 — 「프리뷰를 켰으니 끝」이 아니다.

로컬에서 OpenAPI, list 응답, call 샘플을 평평하게 본 뒤 mcp: true를 켜라. 게이트웨이가 트랜스코드한다. 필드 계약은 프리뷰 한도와 같이 느슨해지면 안 된다.