Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

MCP 서버 등록

Agent Registry를 사용하면 모델 컨텍스트 프로토콜 (MCP) 서버를 자동으로 또는 수동으로 등록하여 개발자와 조정자 에이전트가 AI 생태계 전반에서 표준화된 도구를 탐색하고 호출할 수 있습니다.

Google Kubernetes Engine (GKE) 또는 Cloud Run에 배포된 커스텀 MCP 서버의 자동 등록은 Agent Registry가 사용 설정된 거버넌스 프로젝트 내에 배포된 리소스만 검색합니다. 별도의 Google Cloud 프로젝트에 배포되거나 외부에서 호스팅되는 커스텀 MCP 서버를 등록하려면 외부 MCP 서버 등록을 참조하세요.

MCP 서버 자동 검색

Google 및 Google Cloud 원격 MCP 서버는 자동으로 등록되고 에이전트 레지스트리에 수집됩니다.

프로젝트에서 MCP 지원이 포함된 Google Cloud API(예: Compute Engine API)를 사용 설정하면 해당 MCP 서버와 도구가 즉시 등록되고 에이전트 레지스트리에서 검색할 수 있게 됩니다. 이러한 서버의 도구 사양을 수동으로 구성하거나 업로드할 필요가 없습니다.

위치 및 조건

에이전트 레지스트리가 Google 또는 Google Cloud원격 MCP 서버를 자동으로 등록하면 us-central1와 같은 개별 리전이 아닌 global 위치에만 McpServer 리소스를 만듭니다. 서비스에서 리전 엔드포인트 (REP)를 제공하는 경우 Agent Registry는 해당 단일 global McpServer 리소스의 interfaces 필드에 해당 리전 URL을 나열합니다.

자동으로 등록된 리소스는 global에만 존재하므로 서버를 쿼리하거나 IAP (Identity-Aware Proxy) 액세스 정책을 구성할 때 다음 조건을 염두에 두세요.

자동으로 등록된 서버에 global 사용: --location=global를 사용하여 에이전트 레지스트리에서 서버를 쿼리하거나 --region=global를 사용하여 IAP 정책을 적용할 때 global 위치를 지정합니다. us-central1과 같은 리전을 지정하면 기본적으로 리전 McpServer 리소스가 없으므로 명령어가 NOT_FOUND 오류를 반환합니다.
데이터 레지던시를 위해 리전에 수동으로 등록: 특정 리전에 레지스트리 메타데이터를 보관해야 하는 경우 해당 리전에 MCP 서버와 리전 엔드포인트 URL을 수동으로 등록한 다음 동일한 리전에 IAP 정책을 적용합니다.

자세한 내용은 리전 및 전역 위치의 거버넌스 범위 및 리전 위치에서 원격 MCP 서버를 찾을 수 없음을 참조하세요.

시작하기 전에

Agent Registry 설정
Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.

필요한 역할

Agent Registry에 MCP 서버를 등록하는 데 필요한 권한을 얻으려면 관리자에게 Agent Registry가 사용 설정된 거버넌스 프로젝트에 대한 Agent Registry API 편집자 (roles/agentregistry.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

GKE에서 MCP 서버 등록

GKE에 배포된 커스텀 MCP 서버를 등록하려면 배포 매니페스트에 필수 Kubernetes 라벨 및 주석을 추가합니다. 다음 예시에서는 자동 등록을 위해 구성된 GKE MCP 서버 배포 매니페스트를 보여줍니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-mcp-server
  labels:
    # GKE takes this label and registers the deployment as an MCP server
    registry.gke.io/functional-type: "MCP_SERVER"
  annotations:
    # Endpoint URLs where the GKE controller can access this MCP server
    modelcontextprotocol.info/urls: |
      - https://my-mcp-server.default.svc.cluster.local/mcp
    # Defines structural capabilities for the MCP server card
    modelcontextprotocol.info/capabilities: |
      card:
        endpoint: "/mcp"
        protocol: "HTTP"
spec:
  selector:
    matchLabels:
      app: my-mcp-server
  template:
    metadata:
      labels:
        app: my-mcp-server
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-mcp-server:1.0.0

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

배포 매니페스트를 구성하고 적용하려면 다음을 수행합니다.

Deployment 매니페스트의 metadata.labels에 registry.gke.io/functional-type: "MCP_SERVER" 라벨을 추가합니다.

참고: GKE는 이전 버전과의 호환성을 위해 apphub.cloud.google.com/functional-type: "MCP_SERVER" 주석도 지원합니다. 하지만 GKE 배포에는 registry.gke.io/functional-type: "MCP_SERVER" 라벨을 사용합니다.
Deployment 매니페스트의 metadata.annotations에서 modelcontextprotocol.info/urls 및 modelcontextprotocol.info/capabilities 주석을 제공하여 서버의 엔드포인트 URL과 기능 세부정보를 선언함으로써 MCP 도구의 자동 검색을 사용 설정합니다.
포드 템플릿의 spec.template.metadata.annotations에서 iam.gke.io/spiffe-identity-type: agent-identity 주석으로 에이전트 ID를 구성하여 인증된 통신을 사용 설정합니다.
배포 매니페스트를 클러스터에 적용합니다.

배포를 적용하면 GKE는 서버에서 도구 사양을 가져오려고 자동으로 시도하고 서버와 해당 도구를 Agent Registry의 읽기 전용 McpServer 검색 리소스에 직접 등록합니다. Agent Registry는 배포 이름을 MCP 서버의 표시 이름으로 사용합니다.

Cloud Run에서 MCP 서버 등록

커스텀 MCP 서버를 Cloud Run 서비스로 배포할 때 --functional-type=mcp-server 플래그를 지정하여 자동으로 등록할 수 있습니다. --functional-type=mcp-server 플래그는 Cloud Run 서비스를 표준 컨테이너화된 워크로드가 아닌 MCP 서버로 식별하여 Cloud Run이 Agent Registry에 서버를 등록하도록 지시합니다. 등록 중에 Cloud Run은 서버 이름과 MCP_SERVER 유형을 레지스트리에 자동으로 추가합니다.

--identity-type 플래그를 사용하여 ID 유형을 지정할 수도 있습니다. 예를 들어 agent-identity 또는 service-account ID를 지정합니다. 지정하지 않으면 워크로드는 기본적으로 서비스 계정 ID를 사용합니다.

새 Cloud Run 서비스 또는 기존 Cloud Run 서비스에서 자동 등록을 구성하려면 Cloud Run용 Gemini Enterprise Agent Platform 기능 구성을 참조하세요. Cloud Run에서 MCP 서버를 배포하고 보호하려면 Cloud Run에서 MCP 서버 호스팅 및 MCP 서버 인증을 참조하세요.

외부 MCP 서버 등록

외부 서버 또는 커스텀 API에서 제공하는 도구를 관리하고 재사용하려면 MCP 서버를 수동으로 등록해야 합니다.

MCP 서버를 수동으로 등록하면 Agent Registry가 엔드포인트를 등록합니다. 하지만 서버를 자동으로 검사하여 사용 가능한 도구를 확인하지는 않습니다. 사용자가 MCP 서버에서 사용할 수 있는 정확한 도구를 찾을 수 있도록 하려면 등록 중에 toolspec.json 파일을 업로드하여 도구 사양을 제공해야 합니다.

도구 사양 준비

서버에서 제공하는 도구를 설명하는 toolspec.json 파일을 만듭니다. 이 사양 파일의 최대 파일 크기는 10KB입니다.

JSON 파일은 도구 스키마의 MCP 사양과 일치해야 합니다. 예를 들면 다음과 같습니다.

{
  "tools": [
    {
      "name": "get_customer_info",
      "description": "Retrieves customer details from the database.",
      "annotations": {
        "title": "Get Customer Info",
        "readOnlyHint": true,
        "idempotentHint": true
      }
    },
    {
      "name": "create_support_ticket",
      "description": "Creates a new support ticket in the issue tracking system.",
      "annotations": {
        "title": "Create Support Ticket",
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

자세한 구조 요구사항은 JSON 스키마 및 REST 참조를 확인하세요.

서버 및 도구 등록

MCP 서버를 등록하고 도구 정의를 동시에 업로드합니다.

콘솔

Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.

에이전트 레지스트리로 이동
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
MCP 서버 탭을 선택합니다.
MCP 서버 추가를 클릭합니다.
MCP 서버 세부정보 패널에서 표시 이름, 설명, 지리적 리전을 입력합니다.
도구 사양 섹션에서 MCP 서버 엔드포인트 URL을 입력하고 toolspec.json 파일의 콘텐츠를 붙여넣습니다.

원하는 경우 이 패널에서 도구 가져오기를 클릭하여 URL에서 MCP 도구를 가져옵니다. 이 옵션은 MCP 서버의 엔드포인트 URL이 인터넷을 통해 공개적으로 호스팅되는 경우에만 작동합니다. 이 기능을 사용하여 비공개로 호스팅되는 MCP 서버에서 도구를 가져올 수 없습니다.
다음을 클릭합니다.

MCP 도구 선택 패널에는 MCP 서버의 이름과 설명이 포함된 도구 목록이 표시됩니다.
포함할 MCP 도구를 모두 선택합니다. 이름 또는 값으로 목록에서 도구를 필터링할 수 있습니다.
저장을 클릭합니다.

gcloud

사용하는 사양 플래그에 따라 구성요소가 속하는 리소스 컬렉션이 결정됩니다. 플래그와 리소스 컬렉션의 전체 매핑은 [서비스 리소스 및 검색 리소스](/agent-registry/data-model#service-resources)를 참고하세요.

gcloud agent-registry services create 명령어를 사용하여 도구 사양과 함께 MCP 서버를 등록합니다.

gcloud agent-registry services create SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --mcp-server-spec-type=tool-spec \
    --mcp-server-spec-content=toolspec.json \
    --interfaces=url=SERVER_URL,protocolBinding=PROTOCOL

다음을 바꿉니다.

SERVER_NAME: MCP 서버에 지정할 이름입니다(예: custom-mcp-server). 이름은 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
PROJECT_ID: 프로젝트 ID입니다.
REGION: 레지스트리 리전입니다.
DISPLAY_NAME: 서버에 지정할 인간이 읽을 수 있는 이름입니다(예: Custom MCP Server).
SERVER_URL: MCP 서버의 엔드포인트 URL(예: https://api.example.com/mcp)
PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은 jsonrpc, http-json 또는 grpc입니다. MCP 서버의 경우 이 값은 jsonrpc인 경우가 많습니다.

Terraform

구성하는 사양 블록에 따라 구성요소가 속하는 리소스 컬렉션이 결정됩니다. 사양과 리소스 컬렉션의 전체 매핑은 [서비스 리소스 및 검색 리소스](/agent-registry/data-model#service-resources)를 참고하세요.

MCP 서버를 등록하고 도구를 지정하려면 mcp_server_spec 블록을 사용하여 google_agent_registry_service 리소스를 구성합니다.

resource "google_agent_registry_service" "mcp_server" {
  location     = "REGION"
  service_id   = "SERVER_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external MCP server registered using Terraform."

  interfaces {
    url              = "SERVER_URL"
    protocol_binding = "JSONRPC"
  }

  mcp_server_spec {
    type    = "TOOL_SPEC"
    content = file("toolspec.json")
  }
}

output "server_resource_name" {
  description = "The generated read-only McpServer resource name."
  value       = google_agent_registry_service.mcp_server.registry_resource
}