Register MCP servers

Agent Registry lets you register Model Context Protocol (MCP) servers automatically or manually so that developers and orchestrator agents can discover and invoke standardized tools across your AI ecosystem.

Automatic registration for custom MCP servers deployed on Google Kubernetes Engine (GKE) or Cloud Run only discovers resources deployed within the governance project where Agent Registry is enabled. To register custom MCP servers deployed in separate Google Cloud projects or hosted externally, see Register external MCP servers.

Automatic discovery of MCP servers

Google and Google Cloud remote MCP servers are automatically registered and ingested into Agent Registry.

When you enable a Google Cloud API with MCP support in your project, such as the Compute Engine API, the corresponding MCP server and its tools are immediately registered and made available for discovery in Agent Registry. You don't need to manually configure or upload tool specifications for these servers.

Location and conditions

When Agent Registry automatically registers a Google or Google Cloud remote MCP server, it creates the McpServer resource only in the global location, not in individual regions such as us-central1. If the service provides regional endpoints (REPs), Agent Registry lists those regional URLs in the interfaces field of that single global McpServer resource.

Because the automatically registered resource exists only in global, keep the following conditions in mind when querying the server or configuring Identity-Aware Proxy (IAP) access policies:

Use global for automatically registered servers: specify the global location when you query the server in Agent Registry with --location=global or apply IAP policies to it with --region=global. If you specify a region such as us-central1, the command returns a NOT_FOUND error because no regional McpServer resource exists there by default.
Manually register in a region for data residency: if you need to keep registry metadata in a specific region, manually register the MCP server and its regional endpoint URL in that region, and then apply your IAP policy in that same region.

For more information, see Governance scope across regional and global locations and Remote MCP server not found in a regional location.

Before you begin

Set up Agent Registry.
Get the project ID for the governance project where Agent Registry is enabled.
To use the Google Cloud CLI commands in this document, set up your gcloud CLI environment.

Required roles

To get the permissions that you need to register MCP servers in Agent Registry, ask your administrator to grant you the Agent Registry API Editor (roles/agentregistry.editor) IAM role on the governance project where Agent Registry is enabled. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Register MCP servers from GKE

To register custom MCP servers deployed on GKE, add the required Kubernetes labels and annotations to your deployment manifest. The following example shows a GKE MCP server deployment manifest configured for automatic registration:

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

Replace PROJECT_ID with your Google Cloud project ID.

To configure and apply the deployment manifest, do the following:

In metadata.labels of your Deployment manifest, add the registry.gke.io/functional-type: "MCP_SERVER" label.

Note: GKE also supports the apphub.cloud.google.com/functional-type: "MCP_SERVER" annotation for backward compatibility. However, use the registry.gke.io/functional-type: "MCP_SERVER" label for your GKE deployments.
In metadata.annotations of your Deployment manifest, enable automated discovery of your MCP tools by providing the modelcontextprotocol.info/urls and modelcontextprotocol.info/capabilities annotations to declare the server's endpoint URLs and capability details.
In spec.template.metadata.annotations of the Pod template, enable authenticated communication by configuring Agent Identity with the iam.gke.io/spiffe-identity-type: agent-identity annotation.
Apply the deployment manifest to your cluster.

When you apply the deployment, GKE automatically attempts to obtain the tool specification from the server and registers the server and its tools directly into a read-only McpServer discovery resource in Agent Registry. Agent Registry uses your deployment name as the display name for the MCP server.

Register MCP servers from Cloud Run

You can automatically register custom MCP servers when you deploy them as Cloud Run services by specifying the --functional-type=mcp-server flag. The --functional-type=mcp-server flag identifies the Cloud Run service as an MCP server rather than a standard containerized workload, instructing Cloud Run to register the server with Agent Registry. During registration, Cloud Run automatically adds the server's name and the MCP_SERVER type to the registry.

You can also specify an identity type using the --identity-type flag. For example, specify an agent-identity or service-account identity. If unspecified, the workload defaults to using a service account identity.

To configure automatic registration on a new or existing Cloud Run service, see Configure Gemini Enterprise Agent Platform features for Cloud Run. To deploy and secure MCP servers on Cloud Run, see Host MCP servers on Cloud Run and Authenticate MCP servers.

Register external MCP servers

To manage and reuse tools provided by external servers or custom APIs, you must manually register the MCP server.

When registering an MCP server manually, Agent Registry registers the endpoint. However, it doesn't automatically inspect the server to determine which tools are available. To let users discover the exact tools available on your MCP server, you must provide the tool specifications during registration by uploading a toolspec.json file.

Prepare your tool specification

Create a toolspec.json file that outlines the tools the server provides. The maximum file size for this specification file is 10 KB.

The JSON file must align with the MCP specification for tool schemas, for example:

{
  "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
      }
    }
  ]
}

For detailed structural requirements, see JSON schemas and the REST reference.

Register the server and tools

Console

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
Select the MCP servers tab.
Click Add MCP server.
In the MCP server details panel, enter the display name, a description, and the geographic region.
In the Tool specification section, enter the MCP server endpoint URL and paste the content of your toolspec.json file.

Optionally, click Import tools in this panel to import the MCP tools from the URL. This option only works if the endpoint URL of your MCP server is publicly hosted over the internet. You can't use this feature to import tools from privately hosted MCP servers.
Click Next.

The Select MCP tools panel displays a list of tools with names and descriptions from your MCP server.
Select all the MCP tools that you want to include. You can filter tools from the list by name or value.
Click Save.

gcloud

The specification flags you use determine which resource collection your component belongs to. For a complete mapping of flags to resource collections, see [Service resources and discovery resources](/agent-registry/data-model#service-resources).

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

Replace the following:

SERVER_NAME: the name you want to give to your MCP server, for example, custom-mcp-server. The name must be 4 to 63 characters and can contain only lowercase letters, numbers, and hyphens.
PROJECT_ID: the project ID.
REGION: the registry region.
DISPLAY_NAME: the human-readable name that you want to give to your server, for example, Custom MCP Server.
SERVER_URL: the endpoint URL of the MCP server, for example, https://api.example.com/mcp.
PROTOCOL: the protocol binding for the endpoint. Valid values are jsonrpc, http-json, or grpc. For MCP servers, this value is often jsonrpc.

Terraform

The specification block you configure determines which resource collection your component belongs to. For a complete mapping of specifications to resource collections, see [Service resources and discovery resources](/agent-registry/data-model#service-resources).

To register an MCP server and specify its tools, configure a google_agent_registry_service resource with the mcp_server_spec block:

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
}