Google Cloud API Gateway MCP 적용법: REST API를 에이전트 도구로 노출할 때 확인할 보안 설정

Google Cloud API Gateway가 MCP 서버 역할을 하는 기능을 Public Preview로 제공하기 시작했다. 기존 REST API를 별도 MCP 서버로 다시 만들지 않고, OpenAPI 스펙에 주석을 추가해 에이전트가 호출할 수 있는 도구로 노출하는 방식이다. 에이전트 개발팀 입장에서는 꽤 매력적이다. 이미 운영 중인 인증, quota, logging, backend routing을 그대로 쓰면서 MCP 진입점을 만들 수 있기 때문이다.

하지만 이 기능은 “REST API를 클릭 한 번으로 안전하게 에이전트에게 열어준다”는 뜻이 아니다. MCP는 도구 발견과 호출을 표준화한다. 표준화된 만큼 잘못 열면 더 빨리, 더 넓게 호출된다. 실무에서는 OpenAPI annotation보다 먼저 노출 범위, 인증, 도구 설명, 감사 로그 기준을 정해야 한다.

작동 방식 정리

Google 발표에 따르면 API Gateway는 /mcp 엔드포인트에서 MCP JSON-RPC 요청을 받는다. 에이전트가 tools/call을 보내면 게이트웨이가 이를 해당 REST 요청으로 변환한다. REST path, query, body, header에 인자를 매핑하고, 기존 API Gateway 정책을 적용한 뒤, backend 응답을 MCP 결과로 다시 포장한다.

OpenAPI 3.0.x 또는 3.1.x가 필요하다. OpenAPI 2.0은 지원하지 않는다. 문서 레벨에서 x-google-api-management.mcp를 켜고, 개별 operation에는 x-google-mcp-tool로 도구 이름과 설명을 지정할 수 있다. 각 operation에는 backend와 비어 있지 않은 description이 있어야 한다.

이 구조의 장점은 정책 경로가 하나라는 점이다. REST로 호출하든 MCP로 호출하든 같은 인증, 같은 quota, 같은 logging 경로를 탄다. 기존 API와 MCP 도구를 따로 운영하면 정책이 갈라지고, 어느 한쪽에서 누락이 생긴다. API Gateway 방식은 이 중복을 줄인다.

가장 먼저 막아야 할 것: tools/list 공개

개발 단계에서 가장 편한 설정은 tools/list를 인증 없이 열어두는 것이다. 에이전트가 쉽게 도구 목록과 입력 스키마를 발견할 수 있다. 문제는 이 정보가 공격자에게도 좋은 문서라는 점이다. 도구 이름, 설명, 파라미터 구조, operation 의도가 그대로 보인다.

Google 문서에서도 production에서는 JWT로 discovery를 보호하라고 안내한다. 여기서 주의할 점은 API key로 tools/list를 보호할 수 없다는 내용이다. tools/call은 underlying REST operation의 인증을 따르지만, discovery는 별도 설계가 필요하다. 실무에서는 개발 환경과 운영 환경의 discovery 정책을 분리해야 한다.

운영 기준은 단순하게 잡는 편이 좋다. 내부 에이전트만 쓰는 MCP라면 tools/list도 인증을 요구한다. 외부 파트너에게 일부 도구만 열어야 한다면 별도 gateway와 별도 OpenAPI spec을 만든다. 하나의 거대한 spec에서 operation별로 숨기려 하면 시간이 지날수록 누락이 생긴다.

도구 설명은 UX 문구가 아니라 라우팅 정책이다

LLM은 도구 설명을 보고 언제 어떤 도구를 호출할지 결정한다. 그래서 Returns order status 같은 설명은 부족하다. 좋은 설명은 “언제 쓰는지”, “언제 쓰지 말아야 하는지”, “필수 입력이 무엇인지”, “부작용이 있는지”를 포함해야 한다.

예를 들어 주문 상태 조회 도구라면 “사용자가 배송 위치, 도착 예정일, 주문 진행 상태를 물을 때 사용한다. 주문 취소나 주소 변경에는 사용하지 않는다. orderId가 없으면 먼저 사용자에게 주문 번호를 요청한다”처럼 써야 한다. 결제 취소 도구라면 더 엄격해야 한다. “실제 환불을 실행한다. 사용자가 명시적으로 환불 의사를 확인했고, 정책 검증 도구가 승인한 경우에만 호출한다”처럼 부작용을 드러내야 한다.

도구 설명이 약하면 모델은 비슷해 보이는 도구를 잘못 부른다. REST API에서는 사람이 문서를 읽고 판단하지만, MCP에서는 모델이 설명을 읽고 판단한다. description은 개발자 문서가 아니라 실행 정책의 일부다.

어떤 API를 먼저 노출할 것인가

처음부터 쓰기 API를 열면 위험하다. 추천 순서는 읽기 전용, idempotent operation, 제한된 쓰기 operation, 고위험 쓰기 operation이다.

읽기 전용 API는 주문 조회, 사용자 프로필 조회, 문서 검색처럼 상태를 바꾸지 않는다. 그래도 개인정보 접근 범위와 로그 마스킹은 필요하다. idempotent operation은 같은 요청을 여러 번 보내도 결과가 크게 변하지 않는 작업이다. 예를 들어 계산, 견적 생성, 유효성 검사가 여기에 가깝다.

제한된 쓰기 operation은 임시 초안 생성, 티켓 코멘트 추가, 태그 변경처럼 되돌리기 쉬운 작업이다. 이 단계부터는 사람 승인 또는 정책 검증 도구를 붙이는 게 좋다. 결제, 환불, 권한 변경, 데이터 삭제, 외부 발송 같은 고위험 쓰기는 MCP 노출 전 별도 리뷰가 필요하다. 에이전트가 호출할 수 있다는 사실만으로 운영 리스크가 커진다.

로그와 관측성 설계

MCP 호출은 일반 REST 호출과 같은 backend를 타더라도 로그에는 구분되어야 한다. 최소한 caller가 사람 UI인지, 서버 배치인지, 에이전트 MCP인지 구분하는 필드가 필요하다. tool name, original user intent, session id, request id, policy decision, backend status를 함께 남겨야 나중에 원인을 찾을 수 있다.

특히 실패 로그보다 성공 로그가 중요하다. 에이전트 사고는 HTTP 500보다 HTTP 200에서 더 많이 발생한다. 잘못된 주문을 정상 조회하거나, 잘못된 고객에게 정상 메일을 보내거나, 불필요한 티켓을 정상 생성하는 식이다. 그래서 tool call 자체의 성공 여부만 보면 부족하다. 호출 전후의 목적과 결과를 감사할 수 있어야 한다.

quota도 별도로 봐야 한다. MCP와 REST가 같은 quota를 공유하는 것은 장점이지만, 에이전트가 반복 호출을 만들면 사람 트래픽까지 밀어낼 수 있다. operation별, agent별, tenant별 quota를 분리해서 대량 호출을 막아야 한다.

배포 절차 예시

1단계에서는 기존 OpenAPI spec을 3.0 이상으로 정리한다. operationId가 중복되거나 설명이 빈 엔드포인트를 먼저 고친다. 2단계에서는 읽기 전용 operation 3~5개만 MCP 도구로 표시한다. 3단계에서는 tools/list 인증을 켠다. 개발 환경에서만 unauthenticated discovery를 허용한다.

4단계에서는 에이전트에서 실제 연결한다. ADK나 MCP client에서 gateway의 /mcp endpoint를 바라보게 하고, 기존 API key 또는 JWT를 전달한다. 5단계에서는 도구 호출 로그를 대시보드로 분리한다. 6단계에서는 shadow test를 한다. 에이전트가 어떤 도구를 호출하려 했는지 기록하되 실제 쓰기 operation은 실행하지 않는다.

이 과정을 거쳐도 바로 전면 적용하지 않는다. 고객지원 FAQ, 주문 조회, 내부 문서 검색처럼 피해 범위가 낮은 흐름부터 붙인다. 한 달 정도 호출 로그와 오호출 케이스를 모은 뒤 쓰기 API를 검토하는 편이 안전하다.

실행 체크리스트

• OpenAPI spec을 3.0.x 또는 3.1.x로 정리한다.
• MCP로 노출할 operation을 읽기 전용부터 고른다.
• operation description에 “언제 사용”, “언제 금지”, “필수 입력”, “부작용”을 쓴다.
• tools/list는 운영 환경에서 JWT로 보호한다.
• 개발용 gateway와 운영용 gateway를 분리한다.
• 고위험 쓰기 API는 별도 spec 또는 별도 gateway로 격리한다.
• MCP 호출 로그에 tool name, session id, user intent, request id, backend status를 남긴다.
• agent별·tenant별 quota를 분리한다.
• 쓰기 operation은 shadow test 후 사람 승인 흐름을 붙인다.
• REST 호출과 MCP 호출의 인증 정책이 실제로 같은지 테스트한다.

API Gateway의 MCP 지원은 에이전트 도구 서버를 빠르게 만드는 기능이다. 동시에 기존 API를 에이전트에게 노출하는 권한 변경이기도 하다. 빠른 도입보다 중요한 것은 작은 범위, 강한 인증, 좋은 도구 설명, 충분한 로그다. 이 네 가지가 없으면 MCP는 생산성 기능이 아니라 새로운 장애 통로가 된다.