서론

안녕하세요.

팀랩(teamLab)에서 엔지니어로 근무하고 있는 츠다(Tsuda)입니다.

평소에는 서비스의 유지보수 및 운영, 추가 개발의 요구사항 정의, 개발 방침 검토, 사내 AI 활용 검증 등에 참여하고 있습니다.

저희 팀에서는 엔지니어와 비엔지니어가 동일한 정보를 참조하며 AI를 사용할 수 있는 환경으로서 Gemini Enterprise를 이용하고 있습니다.

Gemini Enterprise는 Google Workspace의 리소스에 쉽게 접근할 수 있습니다.

반면, 태스크 관리(Task Management)에 사용 중인 Redmine의 정보를 참조하려면, Redmine의 정보를 다운로드하여 Google Drive에 업로드하거나, 화면을 스크린샷으로 찍어 붙여넣어야 했습니다.

이러한 수작업은 단발적인 확인이라면 문제가 없습니다.

하지만 티켓의 상황이나 과거 대응 내용을 반복해서 참조하기에는 부담이 남습니다.

그래서 Gemini Enterprise에서 커스텀 MCP (Model Context Protocol)를 경유하여 Redmine의 정보를 참조할 수 있는 구성을 검토했습니다.

이번 구성에서는 MCP 서버를 Cloud Run에 배포하는 방침을 택하였고, Gemini Enterprise 측에서는 Agent Gateway와 Agent Registry를 사용하여 접속했습니다.

MCP 서버 내부 구현에 대한 자세한 설명은 생략하겠습니다.

본 기사에서는 Cloud Run에 배포하는 방침을 결정한 후, Gemini Enterprise에서 MCP를 등록·제어하고 실제로 Redmine까지 도달하게 만드는 접속 절차와 검증 경위를 정리했습니다.

애초에 접속이 가능한가

Google Cloud의 공식 문서에는 Agent Registry에서 MCP 서버를 임포트(Import)하여 Gemini Enterprise 앱에서 이용하는 절차가 있었습니다.

이 절차를 발견함으로써, Redmine의 MCP를 Google Cloud 측의 관리 대상으로 등록하여 Gemini Enterprise에서 이용할 수 있는 가능성이 보였습니다.

Agent Registry란

Agent Registry는 MCP 서버, 툴(Tool), AI 에이전트(Agent) 등을 등록하여 검색이나 관리에 사용하는 카탈로그입니다.

이번 MCP 접속에서는 Cloud Run의 URL을 알고 있는 것만으로는 부족합니다.

MCP 서버와 툴을 Agent Registry에 등록하여, Gemini Enterprise가 참조하는 대상으로 취급할 수 있도록 합니다.

Agent Gateway란

Agent Gateway는 에이전트 간 또는 에이전트와 외부 툴 간의 통신을 관리하는 Google Cloud의 네트워크 컴포넌트(Network Component)입니다.

공식 문서에서는 Client-to-Agent와 Agent-to-Anywhere라는 두 가지 통신 방향이 설명되어 있습니다.

이번 Gemini Enterprise 접속에서 사용하는 것은 에이전트에서 MCP 서버와 같은 외부 대상으로 나가는 Agent-to-Anywhere입니다.

Agent Registry와 Agent Gateway의 관계

Agent Registry는 접속 대상을 등록하고 찾아내기 위한 카탈로그이며, 통신을 중계하는 프록시(Proxy)가 아닙니다.

Agent Gateway는 등록된 대상으로 향하는 에이전트의 아웃바운드(Outbound) 통신을 통제합니다.

이번 구성의 역할을 나누면 다음과 같습니다.

Gemini Enterprise에서 Redmine의 정보를 참조한다
-> Agent Registry에 등록한 MCP를 이용 대상으로 선택한다
-> Agent Gateway에서 아웃바운드 통신을 관리한다
...

이 관계를 파악하지 못했기 때문에, 처음에는 Cloud Run의 URL을 Agent Gateway에 전달하면 접속할 수 있다고 생각했습니다.

Cloud Run에 두는 것만으로는 사용할 수 없었다

Cloud Run에 MCP 서버를 배포하는 방침이라 하더라도, Gemini Enterprise에서 해당 MCP를 사용할 수 있다는 보장은 없습니다.

실제로 다음과 같은 설정이 각각 필요했습니다.

Cloud Run을 배포 대상으로 선택

이번 방침은 MCP 서버를 Cloud Run에 배포하고, HTTPS로 도달할 수 있는 엔드포인트(Endpoint)로 공개하는 것입니다.

Cloud Run을 선택한 이유는 Gemini Enterprise에서 접속할 HTTP 엔드포인트(Endpoint)를 준비하기 쉽고, Secret Manager나 VPC 설정을 Google Cloud 서비스로서 조합할 수 있기 때문입니다.

이러한 판단을 통해 MCP 서버의 구현과 Gemini Enterprise에서 Redmine까지 도달하는 연결 설정을 분리하여 생각할 수 있습니다.

이번 작업의 핵심은 Google Cloud 측의 관리 대상에 MCP 서버를 등록하고, Gemini Enterprise에서 호출할 수 있는 경로를 만드는 것이었습니다.

구성을 제어(Control)와 통신(Communication)으로 나누면 이해하기 쉽습니다.

이 네 가지를 하나의 "연결 설정"으로 생각하면 어디에서 실패했는지 알 수 없게 됩니다.

Agent Gateway 만들기

Gateway의 위치(Location) 결정하기

이번 Agent Gateway는 Gemini Enterprise 애플리케이션과 동일한 Google Cloud 프로젝트 내의 대응하는 리전(Region)에 생성했습니다.

Gemini Enterprise 애플리케이션, Agent Gateway, Agent Registry를 원하는 곳에 개별적으로 배치하면 되는 것은 아닙니다.

애플리케이션의 위치, Gateway의 리전, Registry의 인스턴스를 서로 대응시켜야 합니다.

이 대응 관계는 공식 문서의 샘플 구성에서도 분기됩니다.

글로벌(Global), 멀티 리전(Multi-region), 리전(Region) 중 무엇을 사용하는지에 따라 선택하는 Registry가 달라집니다.

"Agent Gateway는 항상 이 리전"이라고 단정 짓지 않고, Gemini Enterprise 애플리케이션의 위치로부터 역산하여 결정합니다.

Gemini Enterprise의 Engine에 연결하기

Gateway를 생성하는 것만으로는 Gemini Enterprise가 해당 Gateway를 사용한다고 보장할 수 없습니다.

Gemini Enterprise의 Engine(Google Cloud 콘솔 화면상의 "앱" 리소스, Discovery Engine API에서의 설정 단위)에 기본 외향(Egress) Agent Gateway를 연결합니다.

설정 형태는 다음과 같은 리소스 참조 방식입니다.

{
"agentGatewaySetting": {
"defaultEgressAgentGateway": {
...

여기서 지정하는 것은 Cloud Run의 URL이 아닙니다.

Agent Gateway 리소스의 전체 이름(Full Name)입니다.

이 연결 설정이 없는 상태에서 Agent Registry나 Cloud Run을 확인하더라도, Gemini Enterprise 측의 외향 경로(Egress path)는 완성되지 않습니다.

실제 작업에서는 콘솔상의 설정뿐만 아니라, Gemini Enterprise의 Engine과 Gateway를 GET으로 호출하여 연결 설정이 저장되어 있는지 확인했습니다.

이번 구성에서는 Agent Gateway Admin이나 Agent Gateway User 역할을 추가하는 대신, Gemini Enterprise Engine의 서비스 에이전트(Service Agent)에 Agent Registry 참조를 위한 커스텀 역할(projects/PROJECT_ID/roles/agentGatewayRegistryAccess)을 부여했습니다.

500 INTERNAL 에러 발생

Engine과 Agent Gateway의 연결 과정에서 설정값이 명백히 틀렸다고 단정 지을 수 없는 상태임에도, 콘솔과 REST API 모두 500 INTERNAL을 반환했습니다.

이때 Gateway를 계속해서 다시 만드는 방향으로 진행하면 원인이 되는 계층을 놓치게 됩니다.

먼저 Engine과 Gateway의 GET 요청이 성공하는지 확인했습니다.

GET은 성공하는데 PATCH만 500을 반환한다면, 입력값이나 IAM뿐만 아니라 Google 측의 내부 처리나 반영 상태도 원인 후보에 포함됩니다.

기록한 정보는 다음과 같습니다.

• Engine을 가져올 수 있는지 여부
• Agent Gateway를 가져올 수 있는지 여부
• 변경 요청의 HTTP 상태 코드
• 화면에 표시된 트레이스 번호(Trace number)
• 실행 시각 및 대상 리전

이 시점에서 구분된 것은, Engine과 Agent Gateway의 연관 관계에서 GET은 성공하는 반면 PATCH는 500이 발생하는 현상이었습니다.

Google Cloud Support에 티켓 발행

GET으로는 대상 리소스를 가져올 수 있고, PATCH에서는 500 INTERNAL이 발생하는 상태를 재현할 수 있었습니다.

그래서 콘솔 화면만 보고 설정을 다시 만드는 대신, Google Cloud Support에 케이스를 발행했습니다.

이번 경험을 통해, 매니지드 서비스(Managed Service)의 연관 관계에서 재현 가능한 500 에러가 지속될 경우에는 리소스를 계속 늘리기보다, GET 결과와 에러 증적을 갖추어 서포트에 상담하는 것이 더 빠르게 해결에 다가갈 수 있는 방법이 될 수 있음을 알게 되었습니다.

Agent Registry에 MCP 등록하기

URL을 아는 것만으로는 호출할 수 없다

Agent Gateway에서 MCP 서버로 접속하려면, 접속 대상을 Agent Registry에 등록해야 합니다.

Agent Registry에는 MCP 서버뿐만 아니라 엔드포인트(Endpoint)나 도구(Tool) 정보도 연결됩니다.

현재 문서에서는 Agent Gateway가 관리하는 대상을 Registry에 등록할 것을 요구하고 있습니다.

등록되지 않은 외부 MCP 서버로의 통신은 기본적으로 차단됩니다.

따라서 Cloud Run의 URL에 브라우저나 curl로 도달할 수 있다고 해서, Gemini Enterprise에서 이용할 수 있다는 증거는 되지 않습니다.

확인해야 할 대상은 다음 세 가지입니다.

• Gemini Enterprise용 Agent Registry 인스턴스
• 등록한 MCP 서버 또는 엔드포인트
• Gateway가 참조하는 Registry와 등록 대상의 일치 여부

조직 정책(Organization Policy)으로 추가가 거부됨

Agent Registry 등록이 완료되었으므로, 다음으로는 Gemini Enterprise 앱의 연결된 데이터 스토어(Connected Data Store)로서 MCP 서버를 추가합니다.

하지만 이 작업은 조직 정책에 의해 거부되었습니다.

에러에 포함되어 있던 제약 사항은 constraints/discoveryengine.managed.disableCustomMcpServerConnector였습니다.

이 제약 사항이 활성화되어 있으면, 커스텀 MCP 서버를 Gemini Enterprise의 데이터 스토어로 추가할 수 없습니다.

처음에는 Agent Registry를 경유하면 이 제약의 영향을 받지 않을 가능성도 생각했습니다.

하지만 공식 절차에서도 Agent Registry에 등록한 MCP 서버를 Gemini Enterprise 앱의 연결된 데이터 스토어로 추가하게 되어 있습니다.

따라서 Agent Registry를 사용하는 구성이라도, 이 작업에 대한 조직 정책의 영향을 받습니다.

대응책으로 사내 조직 관리자에게 대상 프로젝트 단위의 예외 허용을 요청했습니다.

허용된 후 동일한 작업을 다시 실행하여, MCP 서버를 Gemini Enterprise 앱에 추가할 수 있는 상태가 되었습니다.

Gemini Enterprise 앱으로 임포트하기

Agent Registry에 등록하는 것만으로는 Gemini Enterprise 앱의 사용자가 해당 MCP를 사용할 수 있는 상태가 되지 않습니다.

연결된 Registry로부터 대상 MCP 서버를 Gemini Enterprise 앱의 연결된 데이터 스토어로 추가해야 합니다.

실제 화면에서는 대상 앱의 "연결된 데이터 스토어"에서 새로운 데이터 스토어를 추가하고, MCP 서버를 선택한 뒤, 사용할 도구를 추가했습니다.

이 단계에 이르러서야 비로소 Registry에 등록한 대상이 Gemini Enterprise 앱의 이용 범위에 포함됩니다.

Agent Gateway 설정, Agent Registry 등록, Gemini Enterprise 앱 임포트는 비슷해 보여도 서로 다른 작업입니다.

Registry의 로케이션을 혼동하지 말 것

Agent Registry에는 글로벌(Global), 멀티 리전(Multi-region), 리전(Region) 선택지가 있습니다.

이번에도 Agent Gateway의 로케이션만 보고 Registry를 선택하는 것이 아니라, Gemini Enterprise 애플리케이션의 로케이션과 세트로 확인했습니다.

공식 설정 절차에는 Gemini Enterprise 애플리케이션과 Runtime 에이전트를 동일한 Gateway로 통제하는 경우나, Gemini Enterprise만 별도의 Gateway로 통제하는 경우의 예시가 실려 있습니다.

구성 목적이 바뀌면 참조해야 할 Registry도 바뀝니다.

도구 사양(Tool Specification) 오류를 먼저 해결하기

Registry에 등록할 때는 MCP 도구의 사양도 검증 대상이 됩니다.

이번 등록 작업에서는 인자(Argument)가 없는 도구에 inputSchema를 기술하지 않아서 오류가 발생했습니다.

인자가 없는 도구에도 inputSchema 기술이 필요하다는 것을 알게 되었습니다.

또한, 이 오류는 Agent Registry의 등록 화면에서 멈췄을 때, Cloud Run의 통신 불량과 toolspec의 미비함을 구분하는 단서가 되었습니다.

등록 전에 표시되는 도구 이름, 설명, 입력 스키마(Input Schema)를 확인합니다.

MCP 서버 코드로 돌아가기 전에, Registry가 받는 등록 정보 그 자체를 확인합니다.

Cloud Run에 도달하게 만들기

Agent Gateway와 Agent Registry의 설정이 끝나더라도, Cloud Run에서 Redmine까지 도달한다는 보장은 없습니다.

이번 접속에서 실제로 문제가 되었던 것은 Cloud Run의 송신측 IP였습니다.

처음에는 Redmine에서 거부됨

Cloud Run에서 Redmine으로 액세스하면, Redmine 측의 허용 IP와 일치하지 않아 HTTP 403 오류가 발생했습니다.

MCP의 응답 형식이나 Agent Registry의 등록을 의심하게 됩니다.

하지만 이 403 오류는 MCP 등록 이후 단계인, Cloud Run에서 Redmine으로 나가는 통신 경로의 문제였습니다.

Cloud Run의 아웃바운드(Outbound) IP는 서비스를 실행하는 것만으로는 Redmine의 허용 리스트에 고정할 수 없습니다.

Redmine 측에서 송신측 IP를 제한하고 있는 경우에는 Cloud Run의 출구를 별도로 설계해야 합니다.

VPC 커넥터(VPC connector)와 Cloud NAT를 조합하기

이번에 확인한 경로는 다음과 같습니다.

Cloud Run
-> Serverless VPC Access connector
-> VPC의 루트
...

Cloud Run에는 VPC 커넥터를 설정하고, 아웃바운드 통신에는 all-traffic을 지정했습니다.

그 후 Cloud NAT에 고정 외부 IP를 할당하여 Redmine 측의 허용 리스트에 등록합니다.

gcloud run services update SERVICE --region=REGION --vpc-connector=CONNECTOR_NAME --vpc-egress=all-traffic

이 설정은 Agent Gateway나 Agent Registry를 변경하는 것이 아닙니다.

Cloud Run에서 Redmine으로 나가는 네트워크 경로만 변경합니다.

Google의 현재 문서에서는 Serverless VPC Access connector 외에도 Direct VPC egress도 안내되고 있습니다.

신규 구축 시 어느 것을 선택할지는 고정 IP, 대응 리전(Region), 비용, 기존 VPC와의 관계를 확인하여 결정합니다.

403이 사라진 후에 확인할 사항

고정 IP를 Redmine 측에서 허용한 후, Cloud Run에서 Redmine API에 도달할 수 있음을 확인했습니다.

이때 확인 과정을 두 가지로 나눕니다.

• Cloud Run에서 Redmine까지 TCP와 HTTPS가 통과하는가
• Redmine API 키를 사용한 참조 요청이 성공하는가

전자가 실패하고 있는데 API 키를 계속 조사해 봤자 원인은 찾을 수 없습니다.

후자만 실패하는 경우에는 Secret Manager로부터의 참조, API 키의 유효성, Redmine 측의 권한을 확인합니다.

Redmine API 키는 Secret Manager에 보관하며, Cloud Run의 실행 서비스 계정에는 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 권한이 필요합니다.

어디까지 확인되었는가

무사히 커넥터에 표시되었고, 채팅을 통해 Redmine 티켓 정보를 가져올 수 있었습니다.

이번 작업에서 확인할 수 있었던 것은 단일 Redmine을 대상으로 한 다음의 경로입니다.

Gemini Enterprise
-> 기본 외향(Outbound) Agent Gateway
-> Agent Registry에 등록한 MCP
...

확인 완료된 범위는 다음과 같습니다.

• Gemini Enterprise의 Engine에서 Agent Gateway를 사용하는 연관 설정
• Agent-to-Anywhere로서의 Agent Gateway 이용
• Agent Registry로의 MCP 등록
• Gemini Enterprise 앱으로의 MCP 임포트 (Import)
• Cloud Run 상의 MCP 엔드포인트 (Endpoint) 도달
• Google OAuth를 사용한 MCP 호출 측의 검증
• Cloud Run에서 Redmine으로의 고정 송신원 IP 경로
• Secret Manager를 사용한 Redmine API 키 참조
• Gemini Enterprise로부터의 참조형 MCP 이용

아래는 앞으로 운영 및 유지보수를 진행하며 검토하고 있는 사항입니다.

Gemini Enterprise에서 커스텀 MCP를 이용한다는 목적은 달성했으므로, 이들은 별도의 태스크로 대응해 나갈 예정입니다.

• 복수의 Redmine을 동일한 MCP로 전환하는 운영
• Redmine 추가 시의 회귀 테스트 (Regression Test)
• GitHub Actions를 통한 Cloud Run 배포

접속 작업을 통해 알게 된 점

이번에 가장 시간이 많이 걸린 것은 MCP 서버의 코드가 아니었습니다.

Gemini Enterprise의 Engine, Agent Gateway, Agent Registry, Cloud Run, Redmine의 허용 목록 (Allowlist)을 각각 별개의 책임 영역으로 나누어 확인했을 때, 에러 발생 시의 트러블슈팅 (Troubleshooting)이었습니다.

Agent Gateway를 만들어도 Engine에 연관시키지 않으면 Gemini Enterprise는 사용하지 않습니다.

Agent Registry에 MCP를 등록해도 Gateway가 해당 Registry를 참조하지 않으면 접속 대상이 되지 않습니다.

Registry에 등록한 MCP를 Gemini Enterprise 앱으로 임포트하지 않으면 사용자의 접속된 데이터 스토어 (Data Store)가 되지 않습니다.

Cloud Run까지 요청이 도달하더라도 Redmine 측에서 송신원 IP를 거부하면 검색은 실패합니다.

역으로 말하면, 실패한 지점을 이 순서대로 구분해 나간다면 설정을 무작정 다시 만들 필요가 없습니다.

MCP 서버를 Cloud Run에 두는 것은 접속의 시작점에 불과합니다.

Gemini Enterprise에서 실제로 사용할 수 있는 상태로 만들려면, Agent Registry에서 대상을 등록하고, Agent Gateway를 Engine에 연관시키며, Cloud Run의 출구를 Redmine의 허용 조건에 맞춰야 합니다.

이 구성을 통해 Redmine의 정보를 매번 다운로드하여 Google Drive로 옮기거나, 화면을 스크린샷 찍어 붙여넣는 수작업을 줄이고, Gemini Enterprise에서 참조형 MCP로서 Redmine의 정보를 확인할 수 있게 되었습니다.

이번에는 Cloud Run으로 배포하는 방침을 결정한 후, Gemini Enterprise에서 MCP를 등록·제어하고 실제로 Redmine까지 도달시키기까지의 접속 절차와 검증 경위를 작성했습니다.

끝까지 읽어주셔서 감사합니다.

참고 자료

Discussion