Agent Registry lets you discover and manage Model Context Protocol (MCP) servers and the specific tools they expose.
Official Google and Google Cloud remote MCP servers are automatically registered and ingested into Agent Registry when you enable the supported Google Cloud API in your project. You can also manually register other external MCP servers. For more information, see Register MCP servers.
This document describes how to discover registered MCP servers and tools and how to modify your tool definitions.
Before you begin
Before you can manage MCP servers and tools, register MCP servers in Agent Registry. You also need your project ID to perform these tasks.
To use the gcloud CLI commands in this document, make sure you have set up your Google Cloud CLI environment.
Required roles
To get the permissions that you need to manage MCP servers and tools in Agent Registry, ask your administrator to grant you the following IAM roles on the project:
-
Discover available MCP servers and tools:
Agent Registry API Viewer (
roles/agentregistry.viewer) -
Update tool definitions:
Agent Registry API Editor (
roles/agentregistry.editor)
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.
Discover available MCP servers and tools
After registering MCP servers, you can discover them to bind them to your agents.
List all available MCP servers
You can list all MCP servers registered in your environment and view their detailed configurations, such as their endpoints and associated metadata:
Console
In the Google Cloud console, go to Agent Registry:
From the project picker, select the Google Cloud project where you set up Agent Registry.
Select the MCP servers tab.
The page displays a list of all registered MCP servers and their details, such as name, identifier, description, runtime, and location.
To view the full details of a server, click the server's name.
gcloud
To list all MCP servers in a specific location, use the mcp-servers list
command:
gcloud alpha agent-registry mcp-servers list \
--project=PROJECT_ID \
--location=REGION
Replace the following:
PROJECT_ID: The project ID.REGION: The registry region.
Filter registered MCP servers
If you have multiple servers, or if you want to confirm the registration of a specific server, you can filter the list by the server's metadata:
Console
In the Google Cloud console, go to Agent Registry:
From the project picker, select the Google Cloud project where you set up Agent Registry.
Select the MCP servers tab.
The page displays a list of all registered MCP servers and their details, such as name, identifier, description, runtime, and location.
To filter by location, click the Location menu, select the locations you want to filter, and click Apply.
The page displays a filtered list of the registered MCP servers for your selected conditions.
gcloud
Filter your list to only return resources matching specific metadata, using
the --filter flag:
gcloud alpha agent-registry mcp-servers list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
Replace FILTER_EXPRESSION with the filter expression
for the MCP servers that you want to filter. For example, you can use the
following filters:
- To filter by display name, use
displayName='DISPLAY_NAME'. - To search by the globally unique
identifier (URN), use
mcpServerId='urn:mcp:SERVER_URN'.
View details from an MCP server
View details from a specific MCP server, for example, its tools:
Console
In the Google Cloud console, go to Agent Registry:
From the project picker, select the Google Cloud project where you set up Agent Registry.
Select the MCP servers tab.
The page displays a list of all registered MCP servers and their details, such as name, identifier, description, runtime, and location.
Click the name of the MCP server that you want to view.
The details page includes tabs for the MCP server details.
Click the corresponding tab to view specific MCP server details:
- Overview: Core details from the MCP server, including the server's name, identifier, location, and description. The overview also displays a code snippet to let you build your agents using the Agent Development Kit (ADK).
- Observability: Insights into the operational health and usage of the MCP server. It surfaces application-centric metrics such as latency, traffic, errors, and token spend. This tab integrates with Google Cloud Observability to display real-time performance metrics and system-level utilization to help you manage costs, debug issues, and track user experience. For more information, see the Observability overview.
- Tools: The catalog of capabilities provided by the server. This tab lists the specific functions exposed by an MCP server that agents can invoke to perform specific actions. For each tool, the interface displays its schema, including its name, description, and critical behavioral annotations that guide how an orchestrating agent should interact with it. Click the name of a tool to display a code snippet that lets you build your agents using the ADK.
gcloud
To view the detailed metadata of a specific MCP server, use the
mcp-servers describe command:
gcloud alpha agent-registry mcp-servers describe SERVER_NAME \
--project=PROJECT_ID \
--location=REGION
Replace SERVER_NAME with the name of your MCP
server, for example, custom-mcp-server.
Update tool definitions
If your MCP server adds new tools or changes existing schemas, you must update the registry to reflect these changes. Because the registry doesn't automatically introspect MCP servers, you must manually upload the updated tool specification. The content you upload replaces the existing tool definitions for this service.
For the Agent Registry API, McpServer resources are used for discovery. Therefore,
you must update the registered Service resource directly.
Prepare your new tool specification. Then, update your JSON file with the latest tool definitions:
gcloud alpha agent-registry services update SERVER_NAME \
--project=PROJECT_ID \
--location=REGION \
--mcp-server-spec-content=@TOOL_SPEC
Replace the following:
SERVER_NAME: The name of your MCP server, for example,custom-mcp-server.PROJECT_ID: The project ID.REGION: The registry region.TOOL_SPEC: The name of the new tool specification, for example,new-toolspec.json.