Agent Registry를 사용하면 등록된 모델 컨텍스트 프로토콜 (MCP) 서버와 도구를 검사, 업데이트, 삭제할 수 있으므로 에이전트가 런타임에 정확한 도구 스키마와 엔드포인트를 사용할 수 있습니다. 자동 및 수동으로 등록된 MCP 서버를 검색하고, 수동으로 등록된 도구 정의를 업데이트하고, 더 이상 사용되지 않는 MCP 서버를 삭제할 수 있습니다.
시작하기 전에
- Agent Registry 설정
단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.
Agent Registry에 MCP 서버를 등록합니다.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.
필요한 역할
Agent Registry에서 MCP 서버 및 도구를 관리하는 데 필요한 권한을 얻으려면 관리자에게 Agent Registry가 사용 설정된 거버넌스 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
사용 가능한 MCP 서버 및 도구 검색:
Agent Registry API 뷰어 (
roles/agentregistry.viewer) -
도구 정의 업데이트: Agent Registry API 편집자 (
roles/agentregistry.editor)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
사용 가능한 MCP 서버 및 도구 검색
MCP 서버를 등록한 후에는 이를 검색하여 에이전트에 바인딩할 수 있습니다.
사용 가능한 모든 MCP 서버 나열
환경에 등록된 모든 MCP 서버를 나열하고 엔드포인트 및 관련 메타데이터와 같은 세부 구성을 볼 수 있습니다.
관리 경계를 구성한 경우 관리 프로젝트에서 여러 프로젝트의 MCP 서버를 나열할 수 있습니다.
환경의 모든 MCP 서버를 나열하려면 다음을 수행합니다.
콘솔
Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.
프로젝트 선택 도구에서 에이전트 레지스트리를 설정한 Google Cloud 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버의 목록과 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
서버의 전체 세부정보를 보려면 서버 이름을 클릭합니다.
gcloud
특정 위치의 모든 MCP 서버를 나열하려면 gcloud agent-registry mcp-servers list 명령어를 실행합니다.
gcloud agent-registry mcp-servers list \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
등록된 MCP 서버 필터링
서버가 여러 개 있거나 특정 서버의 등록을 확인하려면 서버의 메타데이터로 목록을 필터링하면 됩니다.
콘솔
Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버의 목록과 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
위치별로 필터링하려면 위치 메뉴를 클릭하고 필터링할 위치를 선택한 후 적용을 클릭합니다.
페이지에 선택한 조건에 따라 등록된 MCP 서버의 필터링된 목록이 표시됩니다.
gcloud
--filter 플래그를 gcloud agent-registry mcp-servers list 명령어에 전달하여 특정 메타데이터와 일치하는 리소스만 반환하도록 목록을 필터링합니다.
gcloud agent-registry mcp-servers list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.FILTER_EXPRESSION: 필터링하려는 MCP 서버의 필터 표현식입니다. 예를 들어 다음 필터를 사용할 수 있습니다.- 표시 이름으로 필터링하려면
displayName='DISPLAY_NAME'를 사용합니다. - 전역 고유 MCP 서버 식별자(URN)로 검색하려면
mcpServerId='urn:mcp:SERVER_URN'를 사용합니다. - 관리 프로젝트를 쿼리할 때 특정 구성원 프로젝트로 필터링하려면
project_id=MEMBER_PROJECT_ID를 사용합니다.
- 표시 이름으로 필터링하려면
Terraform
메타데이터를 기준으로 필터링하여 등록된 특정 MCP 서버를 가져오려면 filter 인수를 사용하여 google_agent_registry_mcp_server 데이터 소스를 구성합니다.
data "google_agent_registry_mcp_server" "filtered_mcp_server" {
location = "REGION"
filter = "displayName=\"DISPLAY_NAME\""
}
다음을 바꿉니다.
REGION: 레지스트리 리전입니다.DISPLAY_NAME: 필터링할 MCP 서버의 인간이 읽을 수 있는 이름입니다(예:Custom MCP Server).
MCP 서버의 세부정보 보기
특정 MCP 서버의 세부정보(예: 도구)를 확인합니다.
콘솔
Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버의 목록과 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
보려는 MCP 서버의 이름을 클릭합니다.
세부정보 페이지에는 MCP 서버 세부정보 탭이 포함되어 있습니다.
해당 탭을 클릭하여 특정 MCP 서버 세부정보를 확인합니다.
- 개요: 서버 이름, 식별자, 위치, 설명을 포함한 MCP 서버의 핵심 세부정보입니다. 개요에는 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 빌드할 수 있는 코드 스니펫도 표시됩니다.
- 모니터링 가능성: MCP 서버의 운영 상태 및 사용량에 대한 통계입니다. 지연 시간, 트래픽, 오류, 토큰 지출과 같은 애플리케이션 중심 측정항목을 표시합니다. 이 탭은 Google Cloud Observability와 통합되어 실시간 실적 측정항목과 시스템 수준 사용률을 표시하여 비용을 관리하고, 문제를 디버그하고, 사용자 환경을 추적하는 데 도움이 됩니다. 자세한 내용은 모니터링 가능성 개요를 참조하세요.
- 도구: 서버에서 제공하는 기능입니다. 이 탭에는 에이전트가 특정 작업을 수행하기 위해 호출할 수 있는 MCP 서버에서 노출하는 특정 함수가 나열됩니다. 각 도구에 대해 인터페이스는 이름, 설명, 조정 에이전트가 도구와 상호작용하는 방식을 안내하는 중요한 동작 주석을 포함한 스키마를 표시합니다. 도구 이름을 클릭하면 ADK를 사용하여 에이전트를 빌드할 수 있는 코드 스니펫이 표시됩니다.
gcloud
특정 MCP 서버의 세부 메타데이터를 보려면 gcloud agent-registry mcp-servers describe 명령어를 실행합니다.
gcloud agent-registry mcp-servers describe SERVER_NAME \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
SERVER_NAME: MCP 서버의 이름입니다(예:custom-mcp-server).PROJECT_ID: 프로젝트 ID입니다. 관리 경계에서 관리 프로젝트 ID 또는 서버가 배포된 구성원 프로젝트의 ID를 지정할 수 있습니다. 반환된 리소스 이름은 MCP 서버의 ID를 보존하고 요청에 지정된 프로젝트를 사용합니다.REGION: 레지스트리 리전입니다.
Terraform
ID를 사용하여 등록된 특정 MCP 서버에 대한 세부정보를 가져오려면 google_agent_registry_mcp_server 데이터 소스를 구성하세요.
data "google_agent_registry_mcp_server" "my_mcp_server" {
location = "REGION"
mcp_server_id = "SERVER_NAME"
}
output "server_create_time" {
description = "The timestamp when the MCP server was registered."
value = data.google_agent_registry_mcp_server.my_mcp_server.create_time
}
output "server_update_time" {
description = "The timestamp when the MCP server was last updated."
value = data.google_agent_registry_mcp_server.my_mcp_server.update_time
}
다음을 바꿉니다.
REGION: 레지스트리 리전입니다.SERVER_NAME: MCP 서버의 고유 식별자입니다(예:custom-mcp-server).
서버 세부정보 및 도구 정의 업데이트
MCP 서버에서 새 도구를 추가하거나 기존 스키마를 변경하는 경우 이러한 변경사항을 반영하도록 레지스트리를 업데이트해야 합니다.
Agent Registry에서 McpServer 리소스는 읽기 전용 검색 리소스입니다.
자동으로 등록된 MCP 서버의 경우 에이전트 레지스트리가 변경사항을 동기화하도록 기본 런타임에서 배포 또는 워크로드를 업데이트합니다. 수동으로 등록된 MCP 서버를 업데이트하려면 해당 Service 리소스가 등록된 프로젝트 ID를 지정하여 쓰기 가능한 Service 리소스를 직접 업데이트해야 합니다. 레지스트리는 수동으로 등록된 MCP 서버를 자동으로 검사하지 않으므로 업데이트된 도구 사양을 수동으로 업로드해야 하며, 이는 서버의 기존 도구 정의를 대체합니다.
콘솔
Google Cloud 콘솔에서 사용 가능한 서버 세부정보를 업데이트합니다.
Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버의 목록과 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
업데이트하려는 서버의 이름을 클릭합니다.
서버의 개요 탭에서 수정을 클릭합니다.
서비스 수정 패널에서 새 이름 또는 설명과 같은 서버의 업데이트된 정보를 입력합니다.
저장을 클릭합니다.
gcloud
새 도구 사양을 준비합니다.
그런 다음 업데이트된 JSON 파일로 gcloud agent-registry services update 명령어를 실행합니다.
gcloud 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). 사양 파일의 최대 파일 크기는 10KB입니다.
Terraform
등록된 MCP 서버의 메타데이터, 엔드포인트 URL 또는 도구 사양을 업데이트하려면 구성에서 기존 google_agent_registry_service 리소스의 매개변수를 수정한 후 terraform apply를 실행합니다.
resource "google_agent_registry_service" "mcp_server" {
location = "REGION"
service_id = "SERVER_NAME"
display_name = "DISPLAY_NAME"
description = "Updated description of the MCP server."
interfaces {
url = "SERVER_URL"
protocol_binding = "JSONRPC"
}
mcp_server_spec {
type = "TOOL_SPEC"
content = file("TOOL_SPEC")
}
}
다음을 바꿉니다.
REGION: 레지스트리 리전입니다.SERVER_NAME: MCP 서버의 이름입니다(예:custom-mcp-server).DISPLAY_NAME: MCP 서버의 사람이 읽을 수 있는 표시 이름(예:Custom MCP Server)SERVER_URL: MCP 서버의 엔드포인트 URL(예:https://api.example.com/mcp)TOOL_SPEC: 업데이트된 도구 사양 파일의 경로입니다(예:new-toolspec.json). 사양 파일의 최대 파일 크기는 10KB입니다.
MCP 서버 삭제
Agent Registry에 자동으로 등록된 MCP 서버를 삭제하려면 기본 MCP 서버를 삭제하거나 프로젝트에서 MCP 서버의 Google Cloud API를 사용 중지해야 합니다. 그러면 서버가 레지스트리에서 자동으로 삭제됩니다.
수동으로 등록된 MCP 서버를 레지스트리에서 삭제하려면 해당 Service 리소스가 등록된 프로젝트 ID를 지정하여 Service 리소스를 삭제해야 합니다. 이 작업을 수행하면 검색 결과에서 MCP 서버가 삭제되고 다른 도구에서 검색할 수 없게 됩니다.
콘솔
Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
이 페이지에는 등록된 모든 MCP 서버의 목록과 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.
삭제하려는 서버의 이름을 클릭합니다.
서버의 개요 탭에서 삭제를 클릭합니다.
확인 대화상자에서
DELETE를 입력하여 작업을 확인합니다.삭제를 클릭합니다.
gcloud
gcloud agent-registry services delete 명령어를 실행합니다.
gcloud agent-registry services delete SERVER_NAME \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
SERVER_NAME: 삭제하려는 MCP 서버의 이름입니다(예:my-mcp-server).PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
Terraform
Terraform 구성에서 MCP 서버를 나타내는 google_agent_registry_service 리소스를 삭제한 후 terraform apply를 실행합니다.
도구 액세스 관리
MCP 서버 및 도구에 엔터프라이즈급 거버넌스 및 보안을 구현합니다. Agent Registry를 중앙 레지스트리로 사용하고 Agent Gateway를 사용하여 활성 정책을 시행합니다.
Agent Gateway를 사용하면 에이전트가 Google Cloud 에서 실행되는지 또는 외부 개발자 도구인지에 관계없이 에이전트와 도구 간의 상호작용을 안전하게 관리할 수 있습니다.
도구 액세스 관리에 대한 자세한 내용은 다음을 참조하세요.
- Identity and Access Management (IAM) 정책 개요: 특정 도구에 액세스할 수 있는 사용자와 액세스 조건을 정의합니다.
- Agent Gateway 개요: 게이트웨이가 모든 에이전트와 도구 간 (MCP) 상호작용에서 보안 및 모니터링 가능성을 적용하는 방법을 이해합니다.
- 보안 발견 사항 보기: Gemini Enterprise Agent Platform을 사용하여 에이전트형 생태계의 보안 통계를 모니터링하고 검토합니다.