Google Cloud API Gateway MCP 적용법: REST API를 에이전트 도구로 노출하는 운영 체크리스트

요약: Google Cloud API Gateway가 Public Preview로 MCP 서버 역할을 지원한다. 기존 REST API를 별도 MCP 서버로 다시 구현하지 않고, OpenAPI 3.x 스펙에 주석을 추가해 에이전트가 호출 가능한 도구로 노출할 수 있다. 실무 포인트는 빠른 연결이 아니라 인증, 도구 설명, tools/list 공개 범위, quota, 로그를 기존 API 정책과 일치시키는 것이다.

왜 MCP Gateway가 필요한가

AI 에이전트를 제품에 넣을 때 가장 먼저 막히는 지점은 모델이 아니다. 이미 회사 안에는 주문 조회, 환불 처리, 고객 상태 확인, 결제 정보 확인 같은 REST API가 있다. 문제는 에이전트가 이 API를 “도구”로 발견하고 안전하게 호출하려면 보통 MCP 서버를 따로 만들어야 한다는 점이다.

별도 MCP 서버를 만들면 중복이 생긴다. 기존 Gateway에 있던 인증, rate limit, logging, routing을 MCP 서버에 다시 구현해야 한다. 구현이 조금만 달라져도 REST 호출과 에이전트 호출의 정책이 어긋난다. 예를 들어 사람용 API는 JWT를 요구하는데 MCP 서버는 API key만 확인한다면, 같은 기능이 다른 보안 수준으로 노출된다.

Google Cloud API Gateway의 MCP 지원은 이 중복을 줄이는 접근이다. OpenAPI 3.0.x 또는 3.1.x 스펙에 MCP 관련 annotation을 넣으면 Gateway가 MCP JSON-RPC 요청을 REST 호출로 변환한다. 기존 REST operation의 인증, quota, logging이 그대로 적용된다.

기본 동작 구조

구조는 단순하다. 에이전트는 Gateway의 /mcp endpoint에 tools/list 또는 tools/call을 보낸다. Gateway는 tools/call 요청을 받아 해당 tool name과 arguments를 OpenAPI operation에 매핑한다. path, query, body, header로 다시 변환한 뒤 기존 backend로 REST 요청을 보낸다. 응답은 MCP result 형태로 다시 감싼다.

이 방식의 장점은 운영 경로가 하나라는 점이다. REST로 호출하든 MCP로 호출하든 같은 operation, 같은 backend, 같은 quota allocation을 사용한다. 에이전트 트래픽을 별도 시스템으로 우회시키지 않아도 된다.

다만 OpenAPI 2.0은 지원하지 않는다. 기존 spec이 Swagger 2.0이라면 먼저 OpenAPI 3.x로 옮겨야 한다. 또한 각 operation에는 backend와 비어 있지 않은 description이 필요하다. description은 문서용 텍스트가 아니라 모델이 도구를 선택하는 신호이므로 매우 중요하다.

OpenAPI 스펙에서 신경 쓸 부분

문서 예시는 x-google-api-management.mcp를 document level에 켜고, 각 operation에 x-google-mcp-tool을 추가하는 방식이다. 여기서 name과 description을 어떻게 쓰느냐가 품질을 좌우한다.

나쁜 설명은 “Returns order status”처럼 결과만 적는다. 좋은 설명은 “사용자가 주문이 어디 있는지 또는 언제 도착하는지 물을 때 사용한다”처럼 사용 조건을 적는다. LLM은 도구 이름보다 설명을 보고 호출 여부를 판단하기 때문이다.

operationId도 안정적으로 관리해야 한다. 내부 API 이름이 getOrderStatus인데 MCP tool name을 get_order_status로 노출할 수 있다. 이때 한번 배포한 tool name을 자주 바꾸면 에이전트 프롬프트, 테스트, 모니터링이 깨진다. REST API의 public contract처럼 MCP tool contract도 버전 관리해야 한다.

또 하나의 실무 포인트는 schema 깊이다. Google 문서에는 deeply nested object schema가 tools/list에서 완전히 렌더링되지 않을 수 있다고 적혀 있다. 에이전트가 호출할 API라면 입력 schema를 너무 깊게 만들지 말고, 필요한 필드를 평평하게 정리하는 편이 낫다.

보안에서 가장 먼저 볼 것

가장 주의할 항목은 tools/list다. 기본적으로 tools/list는 인증 없이 열려 있어 개발에는 편하지만, 프로덕션에서는 tool name과 input schema가 외부에 노출될 수 있다. Google 문서 기준으로 프로덕션에서는 JWT로 discovery를 보호하는 설정을 권장한다. API key는 tools/list 보안에 사용할 수 없다는 점도 중요하다.

tools/call은 underlying REST operation의 인증을 따른다. 즉 도구 목록 조회와 실제 호출은 분리해서 봐야 한다. 목록은 닫았지만 호출은 열려 있거나, 반대로 목록은 열려 있는데 호출만 강하게 막는 식의 불일치가 생기면 운영 중 혼란이 커진다.

또한 MCP 도구는 모델이 호출한다는 점을 잊으면 안 된다. 사람이 API 문서를 읽고 의도를 판단하는 것이 아니라, 모델이 사용자 입력과 tool description을 비교해 호출한다. 따라서 위험한 operation은 단순히 “delete_user” 같은 이름으로 노출하면 안 된다. destructive action은 별도 승인, dry-run, confirmation token 같은 장치를 넣어야 한다.

적용 순서 예시

가장 안전한 도입 순서는 다음과 같다.

1. 읽기 전용 API 하나를 고른다. 주문 조회, 티켓 상태 조회, 문서 검색처럼 부작용이 없는 operation이 좋다.
2. OpenAPI 3.x spec으로 정리한다. description에는 “언제 사용해야 하는지”를 명확히 쓴다.
3. Gateway에서 MCP를 켜되, production discovery는 JWT로 보호한다.
4. ADK나 MCP client에서 /mcp endpoint를 붙인다.
5. tools/list 결과가 기대와 같은지 확인한다.
6. tools/call을 직접 curl로 호출해 REST 응답과 MCP 응답이 일치하는지 본다.
7. 로그에서 REST 호출과 MCP 호출을 구분할 수 있는 필드를 추가한다.

처음부터 100개 API를 열 필요는 없다. Google 문서상 gateway는 최대 1,000 tools까지 제공할 수 있지만, 운영상 좋은 출발점은 3~5개의 읽기 전용 도구다. 모델이 도구를 잘못 고르는지, description이 충분한지, 로그가 추적 가능한지 먼저 봐야 한다.

운영 중 흔한 실패 패턴

첫 번째 실패는 description을 자동 생성된 API 문서 그대로 두는 것이다. “Get order”는 사람에게는 충분할 수 있지만 모델에게는 부족하다. “배송 상태, 운송장, ETA를 물을 때 사용”처럼 의도를 써야 한다.

두 번째 실패는 tools/list를 개발 편의 때문에 계속 공개해두는 것이다. 도구 이름과 schema는 내부 업무 구조를 드러낼 수 있다. 고객 데이터가 직접 노출되지 않더라도 공격자는 tool 목록만 보고 공격 면을 추론할 수 있다.

세 번째 실패는 REST API의 기존 quota를 그대로 믿는 것이다. 사람 UI에서는 한 사용자가 초당 1번 누르는 버튼도, 에이전트는 루프를 돌며 여러 번 호출할 수 있다. MCP 호출 패턴에 맞는 별도 rate limit 관찰이 필요하다.

네 번째 실패는 write operation을 너무 빨리 여는 것이다. 환불, 삭제, 권한 변경, 이메일 발송 같은 작업은 모델이 직접 실행하기 전에 승인 단계를 둬야 한다.

실행 체크리스트

• OpenAPI 2.0 spec이면 3.x로 먼저 마이그레이션한다.
• 읽기 전용 operation 3~5개부터 MCP로 노출한다.
• tool description에는 반환값보다 사용 조건을 쓴다.
• production tools/list는 JWT로 보호한다.
• tools/call 인증은 기존 REST operation과 일치하는지 확인한다.
• destructive action은 MCP에 바로 열지 말고 승인 흐름을 분리한다.
• MCP 호출 로그에 session id, user id, tool name, latency, backend status를 남긴다.
• schema가 너무 깊으면 에이전트용 facade API를 따로 만든다.
• quota는 REST와 공유하되, agent traffic 대시보드는 별도로 본다.

Google Cloud API Gateway의 MCP 지원은 에이전트 연결을 빠르게 만드는 기능이다. 하지만 진짜 가치는 빠른 데모가 아니라 기존 API 운영 체계를 버리지 않고 에이전트 트래픽을 같은 정책 아래 넣는 데 있다. REST API를 이미 잘 관리하고 있다면, MCP Gateway는 새 서버를 하나 더 만드는 대신 기존 운영 규율을 에이전트 세계로 확장하는 길이다.