How to set up Google Cloud Agent Registry and register MCP servers

Agent Registry is a centralized catalog that lets you store, discover, and govern Model Context Protocol (MCP) servers, tools, standalone skills, and AI agents in Google Cloud. In Gemini Enterprise Agent Platform, it is the governance pillar and unified inventory of those agents, servers, skills, and endpoints. Enable it so agents can find governed tools instead of stitching together one-off integrations.

This guide walks through enabling the API, registering MCP servers with tool specifications, and connecting clients to the registry’s remote MCP server.

Enable the Agent Registry API

Agent Registry operates at the project level. You discover and manage agents, servers, skills, and endpoints only in the project where the API is enabled.

Ask an administrator to grant you these IAM roles on the project:

Enable the API: Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
Grant roles for using the API: Project IAM Admin (roles/resourcemanager.projectIamAdmin)
Full access to Agent Registry API resources: Agent Registry API Admin (roles/agentregistry.admin)

If you plan to use the Google Cloud CLI, make sure gcloud is current:

gcloud components update

Enable the Agent Registry API:

gcloud services enable agentregistry.googleapis.com \
    --project=PROJECT_ID

Replace PROJECT_ID with your project ID. Enabling APIs requires the serviceusage.services.enable permission. Project creators typically have this through the Owner role (roles/owner); otherwise use Service Usage Admin.

After the API is on, grant users a role that matches their work:

Agent Registry API Viewer (roles/agentregistry.viewer): view agents, tools, and their attributes
Agent Registry API Editor (roles/agentregistry.editor): edit access to Agent Registry resources
Agent Registry API Admin (roles/agentregistry.admin): perform all actions, including manually registering agents and updating metadata
Agent Registry User (roles/agentregistry.user): create, update, and delete skills and skill revisions

Based on the Agent Registry API data model, you manage Agent, McpServer, Endpoint, Skill, SkillRevision, and Publisher resources. Enabling the API also turns on the Agent Registry remote MCP server.

Register MCP servers

Agent Registry catalogs MCP server endpoints and the tools they expose. How a server lands in the catalog depends on where it runs.

Automatic discovery of Google Cloud MCP servers

Official Google and Google Cloud remote MCP servers are automatically registered and ingested. When you enable a supported Google Cloud API in your project, such as the Compute Engine API, the corresponding MCP server and its tools are immediately registered. You do not need to upload tool specifications for these servers.

Google-managed remote MCP servers are registered in the global location of your project. Apply IAM bindings at global scope with the --region=global flag. Regional IAM bindings, such as --region=us-central1, are not supported for these servers and return a NOT_FOUND error.

Register from GKE

For custom MCP servers on Google Kubernetes Engine, add the registry.gke.io/functional-type: "MCP_SERVER" label. Include annotations that declare endpoint URLs and capability details so Agent Registry can introspect the server and discover tools:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-mcp-server
  labels:
    # GKE takes this label and registers the deployment as an MCP server to the registry
    registry.gke.io/functional-type: "MCP_SERVER"
  annotations:
    # A list of 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
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-mcp-server:1.0.0

When you apply the deployment, GKE automatically attempts to obtain the tool specification from the server and registers the tools into the Agent Registry data model.

Register from Cloud Run

Configure automatic registration for custom MCP servers on Cloud Run with the --functional-type=mcp-server flag when you deploy them. Cloud Run registers the server name and type (MCP_SERVER). You can specify an identity type with --identity-type, for example agent-identity or service-account. If unspecified, the workload defaults to a service account identity.

Automatic registration only discovers resources in the same Google Cloud project. GKE automatically attempts to obtain the tool specification and registers tools; Cloud Run registers the server name and type (MCP_SERVER); manual/external registration records the endpoint and does not introspect tools—you must upload toolspec.json.

Register external MCP servers with toolspec.json

To manage tools from external servers or custom APIs, register the MCP server explicitly. Agent Registry registers the endpoint but does not introspect which tools are available. Provide a toolspec.json file during registration so users can discover those tools. The maximum file size is 10 KB, and the JSON must align with the MCP specification for tool schemas.

You need the Agent Registry API Editor role (roles/agentregistry.editor) on the project.

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 the MCP server, for example custom-mcp-server
PROJECT_ID: the project ID
REGION: the registry region
DISPLAY_NAME: the human-readable name, for example Custom MCP Server
SERVER_URL: the endpoint URL, for example https://api.example.com/mcp
PROTOCOL: the protocol binding. Valid values are jsonrpc, http-json, or grpc. For MCP servers, this value is often jsonrpc.

In the console, go to Agent Registry, open the MCP servers tab, and click Add MCP server. Enter a display name, description, and geographic region. In the tool specification section, enter the MCP server endpoint URL and paste your toolspec.json content. Import tools works only if the endpoint is publicly hosted over the internet, not for privately hosted servers. Select the tools to include and save.

List the servers in your registry to confirm the new entry.

Connect an MCP client to the registry

The Agent Registry remote MCP server lets Gemini CLI, ChatGPT, Claude, and custom applications dynamically discover agents, endpoints, and MCP servers in your environment.

Configure most clients with:

Server name: Agent Registry MCP server
Server URL or Endpoint: https://agentregistry.googleapis.com/mcp
Transport: HTTP
Authentication: Google Cloud credentials, an OAuth client ID and secret, or an agent identity and credentials
OAuth scope: the OAuth 2.0 scope you want to use when connecting

The server uses OAuth 2.0 with IAM. All Google Cloud identities are supported. It requires a principal for IAM control and does not accept API keys. Create a separate identity for agents that use MCP tools so you can control and monitor access.

Agent Registry MCP OAuth scopes include:

https://www.googleapis.com/auth/cloud-platform: full access to all Google Cloud resources
https://www.googleapis.com/auth/agentregistry.read-write: read and write access to Agent Registry resources

Ask an administrator to grant these roles on the project where you use the MCP server:

MCP Tool User (roles/mcp.toolUser) to make MCP tool calls (mcp.tools.call)
Agent Registry API Viewer (roles/agentregistry.viewer) to discover resources
Agent Registry API Editor (roles/agentregistry.editor) to manage resources

The Agent Registry API separates read and write operations. Query the read-only Agent, McpServer, or Endpoint resources to discover capabilities; use the writable Service resource to create, update, and delete entries.

Discovery tools agents use most often:

search_agents: keyword or prefix search for agents by natural language queries, A2A skills, tags, or descriptions
search_mcp_servers: search MCP servers by the tools they offer or their descriptions
get_agent, get_mcp_server, get_endpoint: full metadata and configuration by unique resource name

Search tools are best for natural language. Listing tools such as list_agents, list_mcp_servers, list_endpoints, and list_services return paginated lists when you want to enumerate resources or filter by attributes.

You can list tools without authentication by sending a tools/list HTTP request:

POST /mcp HTTP/1.1
Host: agentregistry.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list"
}

Once connected, try prompts such as finding an agent capable of booking corporate flights, or asking which MCP servers offer BigQuery data tools.

Enable the API in a project you control, then either turn on a supported Google Cloud API so a Google-managed MCP server appears, or register a custom server with toolspec.json. Point Gemini CLI, Claude, ChatGPT, or your own MCP client at https://agentregistry.googleapis.com/mcp and run a search_mcp_servers query.