Agent Registry lets you inspect, update, and remove registered Model Context
Protocol (MCP) servers and tools so that your agents have accurate tool schemas
and endpoints at runtime. You can discover automatically and
[manually registered MCP servers](https://docs.cloud.google.com/agent-registry/register-mcp-servers.md.txt), update
manually registered tool definitions, and remove MCP servers that are no longer
in use.

## Before you begin

1. [Set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).
2. For a single-project setup, get
   [the project ID](https://support.google.com/googleapi/answer/7014113)
   of the [governance project](https://docs.cloud.google.com/agent-registry/overview.md.txt#governance-project)
   where Agent Registry is enabled. If you configured a
   [management boundary](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt) for multiple
   projects, use the ID of your management project for boundary-wide discovery
   and registration, or specify a member project ID for single-project
   operations.

3. [Register MCP servers](https://docs.cloud.google.com/agent-registry/register-mcp-servers.md.txt) in
   Agent Registry.

4. To use the Google Cloud CLI commands in this document,
   [set up your gcloud CLI environment](https://docs.cloud.google.com/agent-registry/setup.md.txt#set-up-cli).

### Required roles

<br />


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 [governance project](https://docs.cloud.google.com/agent-registry/overview.md.txt#governance-project)
where Agent Registry is enabled:

- Discover available MCP servers and tools: [Agent Registry API Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/agentregistry.md.txt#agentregistry.viewer) (`roles/agentregistry.viewer`)
- Update tool definitions: [Agent Registry API Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/agentregistry.md.txt#agentregistry.editor) (`roles/agentregistry.editor`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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.

If you configured a
[management boundary](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt), you can
list MCP servers across multiple projects from your
[management project](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt#management-project).

To list all MCP servers in your environment, do the following:

### Console

1. In the Google Cloud console, go to **Agent Registry**:


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project
   where you [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **MCP servers** tab.

   The page displays a list of all registered MCP servers and their details,
   such as name,
   [identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers),
   description, runtime, and location.
4. To [view the full details of a server](https://docs.cloud.google.com/agent-registry/manage-mcp-tools.md.txt#view-details), click the server's
   name.

### gcloud

To list all MCP servers in a specific location, run the
[`gcloud agent-registry mcp-servers list`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/mcp-servers/list.md.txt)
command:

```bash
gcloud agent-registry mcp-servers list \
    --project=PROJECT_ID \
    --location=REGION
```

Replace the following:

- `PROJECT_ID`: the project ID. If you configured a [management boundary](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt), then specify the ID of your [management project](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt#management-project) to list MCP servers in the specified location across all member projects in the boundary. Each returned [resource name](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#resource-names) preserves the MCP server's ID and uses the project specified in the request.
- `REGION`: the registry [location](https://docs.cloud.google.com/agent-registry/locations.md.txt), such as `us-central1`, `eu`, or `global`. On a management project, specifying a location aggregates MCP servers in that same location across all member projects in the boundary.

### 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

1. In the Google Cloud console, go to **Agent Registry**:


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project where you
   [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **MCP servers** tab.

   The page displays a list of all registered MCP servers and their details,
   such as name,
   [identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers),
   description, runtime, and location.
4. Filter the list by location or runtime:

   - To filter by location, click the **Location** menu, select the locations you want to filter, and click **Apply**.
   - To show or hide system-created MCP servers, click **Show system-created MCP servers** or **Hide system-created MCP servers** in the table toolbar. To list only Google and Google Cloud remote MCP servers, click **Filter** , select **Google MCP** or **Workspace** in the **Runtime** menu, 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 by
passing the `--filter` flag to the
[`gcloud agent-registry mcp-servers list`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/mcp-servers/list.md.txt)
command:

```bash
gcloud agent-registry mcp-servers list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"
```

Replace the following:

- `PROJECT_ID`: the project ID.
- `REGION`: the registry region.
- `FILTER_EXPRESSION`: 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 [MCP server identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers) (URN), use `mcpServerId='urn:mcp:SERVER_URN'`.
  - To list only Google and Google Cloud remote MCP servers, use `mcpServerId:"urn:mcp:googleapis.com:"`.
  - To filter by a specific member project when querying a [management project](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt#management-project), use `mcpServerId:"urn:mcp:projects-MEMBER_PROJECT_NUMBER:"`.

### Terraform

To retrieve a specific registered MCP server by filtering against its
metadata, configure the `google_agent_registry_mcp_server` data source with
the `filter` argument:

```terraform
data "google_agent_registry_mcp_server" "filtered_mcp_server" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}
```

Replace the following:

- `REGION`: the registry region.
- `DISPLAY_NAME`: the human-readable name of the MCP server to filter by, for example, `Custom MCP Server`.

### View details from an MCP server

View details from a specific MCP server, for example, its tools:

### Console

1. In the Google Cloud console, go to **Agent Registry**:


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project where you
   [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **MCP servers** tab.

   The page displays a list of all registered MCP servers and their details,
   such as name,
   [identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers),
   description, runtime, and location.
4. Click the name of the MCP server that you want to view.

   The details page includes tabs for the MCP server details.
5. Click the corresponding tab to view specific MCP server details:

   - **Overview** : core details from the MCP server, including the server's name, [identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers), location, and description. The overview also displays a code snippet to let you build your agents using the [Agent Development Kit (ADK)](https://docs.cloud.google.com/agent-registry/resolve-endpoints-and-build-orchestrators.md.txt).
   - **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](https://docs.cloud.google.com/gemini-enterprise-agent-platform/optimize/observability/overview.md.txt).
   - **Tools** : the 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](https://docs.cloud.google.com/agent-registry/resolve-endpoints-and-build-orchestrators.md.txt).

### gcloud

To view the detailed metadata of a specific MCP server, run the
[`gcloud agent-registry mcp-servers describe`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/mcp-servers/describe.md.txt)
command:

```bash
gcloud agent-registry mcp-servers describe SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION
```

Replace the following:

- `SERVER_NAME`: the name of your MCP server, for example, `custom-mcp-server`.
- `PROJECT_ID`: the project ID. In a [management boundary](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt), you can specify either the management project ID or the ID of the member project where the server is deployed. The returned resource name preserves the MCP server's ID and uses the project specified in your request.
- `REGION`: the registry region.

### Terraform

To retrieve details about a specific registered MCP server using its ID,
configure the `google_agent_registry_mcp_server` data source:

```terraform
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
}
```

Replace the following:

- `REGION`: the registry region.
- `SERVER_NAME`: the unique identifier of your MCP server, for example, `custom-mcp-server`.

## Update server details and tool definitions

If your MCP server adds new tools or changes existing schemas, you must update
the registry to reflect these changes.

In Agent Registry, `McpServer` resources are read-only discovery resources.
For automatically registered MCP servers, update the deployment or workload in
its underlying runtime so that Agent Registry synchronizes the changes. To
update a manually registered MCP server, you must update its writable `Service`
resource directly by specifying the project ID where that `Service` resource was
registered. Because the registry doesn't automatically inspect manually
registered MCP servers, you must manually upload the updated tool
specification, which replaces the existing tool definitions for the server.

### Console

Update available server details from the Google Cloud console:

1. In the Google Cloud console, go to **Agent Registry**:


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project where you
   [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **MCP servers** tab.

   The page displays a list of all registered MCP servers and their details,
   such as name,
   [identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers),
   description, runtime, and location.
4. Click the name of the server that you want to update.

5. On the **Overview** tab of the server, click
   **Edit**.

6. In the **Edit service** panel, enter the updated information of your
   server, such as its new name or description.

7. Click **Save**.

### gcloud

[Prepare your new tool specification](https://docs.cloud.google.com/agent-registry/register-mcp-servers.md.txt#prepare-tool-spec).
Then, run the
[`gcloud agent-registry services update`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/services/update.md.txt)
command with your updated JSON file:

```bash
gcloud 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 path to the new tool specification file, for example, `new-toolspec.json`. The maximum file size for the specification file is 10 KB.

### Terraform

To update your registered MCP server's metadata, endpoint URL, or tool
specification, modify the parameters of the existing
`google_agent_registry_service` resource in your configuration, and then run
`terraform apply`:

```terraform
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")
  }
}
```

Replace the following:

- `REGION`: the registry region.
- `SERVER_NAME`: the name of your MCP server, for example, `custom-mcp-server`.
- `DISPLAY_NAME`: the human-readable display name of your MCP server, for example, `Custom MCP Server`.
- `SERVER_URL`: the endpoint URL of the MCP server, for example, `https://api.example.com/mcp`.
- `TOOL_SPEC`: the path to your updated tool specification file, for example, `new-toolspec.json`. The maximum file size for the specification file is 10 KB.

## Remove an MCP server

To delete MCP servers that were automatically registered to Agent Registry,
you must delete the underlying MCP server or disable the Google Cloud API
of the MCP server in your project. The server is then automatically removed from
the registry.

To remove a manually registered MCP server from the registry, you must delete
its `Service` resource by specifying the project ID where that `Service`
resource was registered. This action removes the MCP server from search results
and makes it undiscoverable to other tools:

### Console

1. In the Google Cloud console, go to **Agent Registry**:


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project where you
   [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **MCP servers** tab.

   The page displays a list of all registered MCP servers and their details,
   such as name,
   [identifier](https://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txt#mcp-server-identifiers),
   description, runtime, and location.
4. Click the name of the server that you want to remove.

5. On the **Overview** tab of the server, click
   **Delete**.

6. In the confirmation dialog, enter `DELETE` to confirm the action.

7. Click **Delete**.

### gcloud

Run the
[`gcloud agent-registry services delete`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/services/delete.md.txt)
command:

```bash
gcloud agent-registry services delete SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION
```

Replace the following:

- `SERVER_NAME`: the name of the MCP server you want to remove, for example, `my-mcp-server`.
- `PROJECT_ID`: the project ID.
- `REGION`: the registry region.

### Terraform

Remove the `google_agent_registry_service` resource representing the MCP
server from your Terraform configuration, and then run `terraform apply`.

## Govern tool access

Implement enterprise-grade governance and security for your MCP servers and
tools. Use Agent Registry as your central registry and
[Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview.md.txt)
for active policy enforcement.

Agent Gateway lets you securely govern interactions between agents and
tools, regardless of whether those agents are running on Google Cloud or
are external developer tools.

For more information about governing tool access, see the following:

- [Identity and Access Management (IAM) policies overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/overview.md.txt): define who can access specific tools and under what conditions.
- [Agent Gateway overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview.md.txt): understand how the gateway enforces security and observability across all agent-to-tool (MCP) interactions.
- [View security findings](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/view-security-findings.md.txt): monitor and review security insights for your agentic ecosystem using Gemini Enterprise Agent Platform.