REST API를 MCP 도구로 바꾸는 운영 가이드: OpenAPI 설명·인증·로그를 먼저 정리하라

REST API를 MCP 도구로 바꾸는 일은 코드 생성 문제가 아니다. 에이전트가 안전하게 호출할 수 있는 운영 경로를 만드는 문제다. Google Cloud API Gateway의 MCP 공개 프리뷰는 이 방향을 잘 보여준다. 별도 MCP 서버를 만들지 않고 기존 OpenAPI 스펙과 게이트웨이를 활용할 수 있지만, 준비 없이 켜면 도구 목록만 늘고 운영 리스크도 같이 늘어난다.

이 글은 특정 클라우드 기능 홍보가 아니라 실무 체크리스트다. 이미 REST API를 가진 팀이 MCP 노출을 검토할 때 무엇부터 정리해야 하는지 설명한다. 핵심은 세 가지다. 도구 설명을 LLM 친화적으로 다시 쓰고, discovery와 call 인증을 분리하고, REST 로그와 MCP 로그를 같은 기준으로 남기는 것이다.

검색 의도는 “MCP 도구 만들기”, “OpenAPI MCP”, “AI 에이전트 REST API 연동”이다. 읽는 사람은 대개 백엔드 개발자, 플랫폼 엔지니어, AI 기능을 붙이려는 스타트업 개발자다.

1단계: API 전체가 아니라 업무 시나리오를 고른다

처음부터 내부 API 전체를 MCP로 열면 안 된다. 에이전트는 도구가 많을수록 선택 실수를 하기 쉽다. 사람은 API 문서를 보고 판단하지만, 모델은 tool name, description, parameters를 보고 확률적으로 고른다. 비슷한 이름의 API가 많으면 잘못된 도구 호출이 늘어난다.

첫 파일럿은 하나의 업무 시나리오로 제한하는 편이 좋다. 예를 들어 고객지원 에이전트라면 다음 정도면 충분하다.

• 주문 상태 조회
• 배송 추적 조회
• 반품 가능 여부 확인
• 반품 요청 생성
• 고객 메모 추가

이때도 쓰기 API는 마지막에 연다. 먼저 조회 API만 연결해 모델이 올바른 도구를 고르는지 확인한다. 조회 도구 선택률, 실패율, latency를 본 뒤 반품 요청 같은 쓰기 API를 추가한다.

2단계: OpenAPI description을 다시 쓴다

일반 API 문서의 description은 보통 짧다. “Returns order status”처럼 작성되어 있다. 사람에게는 충분할 수 있지만 LLM에게는 부족하다. MCP 도구 설명은 “언제 사용해야 하는지”와 “언제 사용하면 안 되는지”를 포함해야 한다.

나쁜 예시는 이렇다.

getOrderStatus: Returns the current status of an order.

좋은 예시는 다르다.

get_order_status: 사용자가 주문이 어디 있는지, 배송 예정일이 언제인지, 주문이 처리 중인지 묻는 경우 사용한다. 결제 취소나 주소 변경에는 사용하지 않는다.

이 차이가 도구 선택 품질을 만든다. description에는 다음 항목을 넣는다.

• 사용해야 하는 사용자 의도
• 사용하지 말아야 하는 상황
• 필요한 식별자 형식
• 응답에 포함되는 핵심 필드
• 실패 시 사용자에게 안내할 메시지 기준

도구 설명은 API 문서가 아니라 모델용 라우팅 규칙이다.

3단계: discovery 인증과 실행 인증을 나눈다

MCP에는 도구 목록을 보는 tools/list와 실제 도구를 실행하는 tools/call이 있다. 많은 팀이 실행 인증만 생각한다. 하지만 도구 목록과 입력 스키마도 민감 정보가 될 수 있다. 내부 시스템 이름, 업무 흐름, 파라미터 구조가 노출되기 때문이다.

운영 환경에서는 discovery도 보호해야 한다. Google API Gateway 문서 기준으로도 프로덕션에서는 JWT로 tools/list를 보호하라고 안내한다. API key만으로는 이 메서드를 보호할 수 없다는 제한도 있다.

권장 기준은 다음과 같다.

• 개발 환경: 제한된 테스트 계정으로 discovery 허용
• 스테이징: 사내 SSO 또는 JWT 필요
• 운영: 에이전트별 JWT와 audience 검증
• 외부 파트너: 별도 게이트웨이와 별도 tool subset 제공

도구 목록을 볼 수 있는 주체와 도구를 실행할 수 있는 주체가 항상 같을 필요는 없다. 이 둘을 분리해야 감사가 쉬워진다.

4단계: quota와 rate limit을 에이전트 기준으로 다시 본다

MCP 호출이 REST 호출로 변환되면 quota를 기존 REST API와 공유할 수 있다. 장점이지만 함정도 있다. 사람 UI에서 한 번 누르던 작업을 에이전트는 여러 번 시도할 수 있다. 불확실한 상태에서 같은 조회를 반복하거나, 실패한 call을 재시도하거나, 여러 도구를 순차 호출할 수 있다.

따라서 기존 quota를 그대로 두기보다 에이전트 전용 client id, user agent, JWT subject를 분리해야 한다. 그래야 대시보드에서 사람 트래픽과 에이전트 트래픽을 구분할 수 있다.

꼭 봐야 할 지표는 다음과 같다.

• tool name별 호출 수
• 사용자 세션별 평균 tool call 수
• 동일 파라미터 반복 호출 비율
• 4xx와 5xx 비율
• tool call latency p95
• 모델 응답 실패와 backend 실패의 분리

이 지표가 없으면 “AI가 느리다”는 말만 남고 원인을 찾기 어렵다.

5단계: 쓰기 API에는 승인 단계를 둔다

조회 API는 실패해도 피해가 제한적이다. 쓰기 API는 다르다. 환불, 이메일 발송, 권한 변경, 주문 취소, 데이터 삭제 같은 작업은 에이전트가 바로 실행하게 두면 안 된다. 처음에는 dry-run 응답을 만들고, 모델이 제안한 action을 사람이 승인하는 구조가 안전하다.

예를 들어 create_return_request를 바로 실행하지 말고, 먼저 preview_return_request를 호출하게 한다. 응답에는 예상 환불액, 정책 근거, 필요한 사용자 확인 항목을 포함한다. 사용자가 확인하면 실제 생성 API를 호출한다.

이 패턴은 개발 속도를 크게 늦추지 않는다. 오히려 에이전트가 무슨 일을 하려는지 명확하게 보여주므로 사용자 신뢰가 올라간다.

실행 체크리스트

• MCP로 열 첫 업무 시나리오를 하나만 고른다.
• 조회 API부터 시작하고 쓰기 API는 나중에 추가한다.
• OpenAPI 3.x 전환 여부를 확인한다.
• 도구 description에 사용 의도와 금지 상황을 쓴다.
• tools/list와 tools/call 인증을 분리한다.
• 에이전트 전용 client id 또는 JWT subject를 둔다.
• REST 로그에 tool name, session id, backend status를 함께 남긴다.
• 쓰기 API는 preview와 approve 단계를 둔다.
• 실패 메시지는 모델용과 사용자용을 구분한다.
• 도구가 20개를 넘으면 업무별 MCP endpoint 분리를 검토한다.

MCP 전환은 “AI 연결” 프로젝트가 아니다. 기존 API 운영 체계에 에이전트라는 새 클라이언트를 추가하는 일이다. 그래서 정답은 빠른 래퍼 작성보다 좋은 스펙, 권한, 로그다.