Agent Registry를 사용하면 모델 컨텍스트 프로토콜 (MCP) 서버와 서버에서 노출하는 특정 도구를 검색하고 관리할 수 있습니다.
공식 Google 및 Google Cloud 원격 MCP 서버는 프로젝트에서 지원되는 Google CloudAPI를 사용 설정하면 자동으로 등록되어 Agent Registry에 수집됩니다. 다른 외부 MCP 서버를 수동으로 등록할 수도 있습니다. 자세한 내용은 MCP 서버 등록을 참고하세요.
이 문서에서는 등록된 MCP 서버와 도구를 검색하는 방법과 도구 정의를 수정하는 방법을 설명합니다.
시작하기 전에
MCP 서버와 도구를 관리하려면 먼저 에이전트 레지스트리에 MCP 서버를 등록해야 합니다. 이러한 작업을 수행하려면 프로젝트 ID도 필요합니다.
이 문서에서 gcloud CLI 명령어를 사용하려면 Google Cloud CLI 환경을 설정해야 합니다.
필요한 역할
에이전트 레지스트리에서 MCP 서버와 도구를 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
사용 가능한 MCP 서버 및 도구 검색:
에이전트 레지스트리 API 뷰어 (
roles/agentregistry.viewer) -
도구 정의 업데이트:
Agent Registry API 편집자 (
roles/agentregistry.editor)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
사용 가능한 MCP 서버 및 도구 검색
MCP 서버를 등록한 후 이를 검색하여 에이전트에 바인딩할 수 있습니다.
사용 가능한 모든 MCP 서버 나열
환경에 등록된 모든 MCP 서버를 나열하고 엔드포인트, 연결된 메타데이터와 같은 세부 구성을 볼 수 있습니다.
콘솔
Google Cloud 콘솔에서 Agent Registry로 이동합니다.
프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버와 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
서버의 전체 세부정보를 보려면 서버 이름을 클릭합니다.
gcloud
특정 위치에 있는 모든 MCP 서버를 나열하려면 mcp-servers list 명령어를 사용합니다.
gcloud alpha agent-registry mcp-servers list \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
등록된 MCP 서버 필터링
서버가 여러 대이거나 특정 서버의 등록을 확인하려면 서버의 메타데이터로 목록을 필터링하면 됩니다.
콘솔
Google Cloud 콘솔에서 Agent Registry로 이동합니다.
프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버와 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
위치별로 필터링하려면 위치 메뉴를 클릭하고 필터링할 위치를 선택한 다음 적용을 클릭합니다.
이 페이지에는 선택한 조건에 따라 필터링된 등록된 MCP 서버 목록이 표시됩니다.
gcloud
--filter 플래그를 사용하여 특정 메타데이터와 일치하는 리소스만 반환하도록 목록을 필터링합니다.
gcloud alpha agent-registry mcp-servers list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
FILTER_EXPRESSION을 필터링하려는 MCP 서버의 필터 표현식으로 바꿉니다. 예를 들어 다음 필터를 사용할 수 있습니다.
- 표시 이름으로 필터링하려면
displayName='DISPLAY_NAME'를 사용하세요. - 전역 고유 식별자 (URN)로 검색하려면
mcpServerId='urn:mcp:SERVER_URN'를 사용하세요.
MCP 서버의 세부정보 보기
특정 MCP 서버의 세부정보(예: 도구)를 확인합니다.
콘솔
Google Cloud 콘솔에서 Agent Registry로 이동합니다.
프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버와 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
보려는 MCP 서버의 이름을 클릭합니다.
세부정보 페이지에는 MCP 서버 세부정보 탭이 포함되어 있습니다.
해당 탭을 클릭하여 특정 MCP 서버 세부정보를 확인합니다.
- 개요: 서버 이름, 식별자, 위치, 설명을 비롯한 MCP 서버의 핵심 세부정보입니다. 개요에는 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 빌드할 수 있는 코드 스니펫도 표시됩니다.
- 관측 가능성: MCP 서버의 운영 상태 및 사용에 관한 유용한 정보입니다. 지연 시간, 트래픽, 오류, 토큰 사용량과 같은 애플리케이션 중심 측정항목을 표시합니다. 이 탭은 Google Cloud Observability와 통합되어 실시간 성능 측정항목과 시스템 수준 사용률을 표시하므로 비용을 관리하고, 문제를 디버깅하고, 사용자 환경을 추적하는 데 도움이 됩니다. 자세한 내용은 관측 가능성 개요를 참고하세요.
- 도구: 서버에서 제공하는 기능의 카탈로그입니다. 이 탭에는 에이전트가 특정 작업을 실행하기 위해 호출할 수 있는 MCP 서버에서 노출된 특정 함수가 나열됩니다. 각 도구의 경우 인터페이스에 이름, 설명, 오케스트레이션 에이전트가 도구와 상호작용하는 방법을 안내하는 중요한 동작 주석을 비롯한 스키마가 표시됩니다. 도구 이름을 클릭하여 ADK를 사용하여 에이전트를 빌드할 수 있는 코드 스니펫을 표시합니다.
gcloud
특정 MCP 서버의 자세한 메타데이터를 보려면 mcp-servers describe 명령어를 사용합니다.
gcloud alpha agent-registry mcp-servers describe SERVER_NAME \
--project=PROJECT_ID \
--location=REGION
SERVER_NAME을 MCP 서버 이름(예: custom-mcp-server)으로 바꿉니다.
도구 정의 업데이트
MCP 서버에서 새 도구를 추가하거나 기존 스키마를 변경하는 경우 이러한 변경사항을 반영하도록 레지스트리를 업데이트해야 합니다. 레지스트리에서 MCP 서버를 자동으로 인트로스펙트하지 않으므로 업데이트된 도구 사양을 수동으로 업로드해야 합니다. 업로드한 콘텐츠는 이 서버의 기존 도구 정의를 대체합니다.
Agent Registry API의 경우 McpServer 리소스가 검색에 사용됩니다. 따라서 등록된 Service 리소스를 직접 업데이트해야 합니다.
새 도구 사양을 준비합니다. 그런 다음 최신 도구 정의로 JSON 파일을 업데이트합니다.
gcloud alpha agent-registry services update SERVER_NAME \
--project=PROJECT_ID \
--location=REGION \
--mcp-server-spec-content=TOOL_SPEC
다음을 바꿉니다.
SERVER_NAME: MCP 서버의 이름입니다(예:custom-mcp-server).PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.TOOL_SPEC: 새 도구 사양의 이름입니다(예:new-toolspec.json).
도구 액세스 관리
MCP 서버 및 도구에 엔터프라이즈급 거버넌스 및 보안을 구현합니다. 에이전트 레지스트리를 중앙 집중식 카탈로그로 사용하고 에이전트 게이트웨이를 사용하여 활성 정책을 적용합니다.
에이전트 게이트웨이를 사용하면 에이전트가 Google Cloud 에서 실행되는지 아니면 외부 개발자 도구에서 실행되는지에 관계없이 에이전트와 도구 간의 상호작용을 안전하게 관리할 수 있습니다.
도구 액세스 관리에 대한 자세한 내용은 다음을 참고하세요.
- IAM 정책 개요: 특정 도구에 액세스할 수 있는 사용자와 액세스 조건을 정의합니다.
- 에이전트 게이트웨이 개요: 게이트웨이가 모든 에이전트-도구 (MCP) 상호작용에서 보안과 관측 가능성을 적용하는 방법을 알아봅니다.
- 보안 결과 보기: Gemini Enterprise Agent Platform을 사용하여 에이전트형 생태계의 보안 통계를 모니터링하고 검토합니다.