Set up Agent Registry

To register and discover your AI agents, Model Context Protocol (MCP) servers, standalone skills, and endpoints in Agent Registry, you must enable the Agent Registry API in your Google Cloud project. The project where you enable Agent Registry serves as your governance project.

You can set up Agent Registry in a single governance project or across multiple projects by configuring a management boundary where a central management project serves as your governance project.

Before you begin

Configure Agent Registry either in a single project or across multiple projects:

Required roles

To get the permissions that you need to set up Agent Registry, ask your administrator to grant you the following IAM roles on your Google Cloud project:

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.

Set up your Google Cloud CLI environment

If you plan to use the gcloud CLI for Agent Registry, follow these steps:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Update the gcloud CLI to the most recent version with the gcloud components update command:

    gcloud components update

  3. If you plan to use Preview features, install the alpha component with the gcloud components install command:

    gcloud components install alpha

Enable the Agent Registry API

Use your project ID to enable APIs:

Console

For a single project, enable the Agent Registry API on your project:

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

For multiple projects (management boundary), enable the Resource Manager API on the project that you use for configuration:

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

gcloud

  • For a single project, enable the Agent Registry API on your project with the gcloud services enable command:

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

  • For multiple projects (management boundary), enable the Resource Manager API on the project that you use for configuration:

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

Replace PROJECT_ID with the project ID of your standalone governance project, or the project that you want to use as the management project for your management boundary.

Configure a management boundary for multiple projects

To use Agent Registry across multiple Google Cloud projects, configure a management boundary. A management boundary groups one or more Google Cloud member projects into a central management project that serves as your governance project so that you can discover and govern AI agents, MCP servers, and tools across projects.

You define a management boundary in Resource Manager. For step-by-step instructions, see Configure management boundaries in the Resource Manager documentation.

For an architectural overview of how BoundaryConfig, Boundary, and CapabilityConfig resources work together, see Cross-project boundaries.

When you create a CapabilityConfig resource with agent-management, Resource Manager automatically enables agentregistry.googleapis.com on the management project. After establishing your management boundary:

  1. If needed for local operations within individual member projects, enable the Agent Registry API on those member projects.
  2. Grant the required roles and permissions to users and service accounts on the management project.

When you list or search for agents or MCP servers in a location on the management project, Agent Registry aggregates and returns auto-discovered resources in that location from all member projects in the boundary, alongside any registered Service resources created directly in that location on the management project. Each returned resource name preserves the component's ID and uses the project specified in the request.

Grant permissions

To view and manage resources in Agent Registry, you must grant users the appropriate Identity and Access Management (IAM) permissions.

Grant your users one or more of the following Agent Registry roles:

  • Agent Registry API Viewer (roles/agentregistry.viewer): view and search agents, MCP servers, tools, standalone skills, skill revisions, publishers, endpoints, and bindings.
  • Agent Registry API Editor (roles/agentregistry.editor): view and edit Agent Registry resources, including registering, updating, and deleting agents, MCP servers, tools, endpoints, standalone skills, and skill revisions.
  • Agent Registry API Admin (roles/agentregistry.admin): perform all actions on Agent Registry resources, including registering and managing agents, MCP servers, tools, endpoints, standalone skills, skill revisions, bindings, and skill IAM policies.
  • Agent Registry User (roles/agentregistry.user): view all Agent Registry resources, and create, update, and delete standalone skills and skill revisions without edit access to agents, MCP servers, or endpoints.

To learn how to grant IAM roles on a project, see Manage access to projects, folders, and organizations.

Change your Agent Registry project

If you want to change the project where you use Agent Registry and remove dependencies from the old project, disable the Agent Registry API in the old project. After you have disabled the Agent Registry API in the old project, you can enable it in another project. Your data isn't migrated, and you must recreate your resources in this new project.

Disable the Agent Registry API

If you no longer want to use Agent Registry, disable the Agent Registry API on the project:

Console

  1. In the Google Cloud console, go to the Agent Registry API management page:

    Go to Agent Registry API

  2. From the project picker, select the Google Cloud project where you set up Agent Registry.

  3. Click Disable API.

  4. In the confirmation dialog, click Disable.

gcloud

Disable the Agent Registry API in your project with the gcloud services disable command:

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

Replace PROJECT_ID with the ID of the project.

What's next