Use the Agent Retrieval remote MCP server to connect to AI and custom applications

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This document shows you how to use the Gemini Enterprise Agent Platform remote Model Context Protocol (MCP) server to connect with AI applications including Gemini CLI, ChatGPT, Claude, and custom applications you are developing. The Agent Retrieval remote MCP server lets you access and run Agent Retrieval tools to inspect collections and indexes, and perform vector, semantic, hybrid, and text search over your data from your AI-enabled development environments and AI agent platforms. The Gemini Enterprise Agent Platform remote MCP server is enabled when you enable the Gemini Enterprise Agent Platform API.

Model Context Protocol (MCP) standardizes how large language models (LLMs) and AI applications or agents connect to external data sources. MCP servers let you use their tools, resources, and prompts to take actions and get updated data from their backend service.

What's the difference between local and remote MCP servers?

Local MCP servers

Typically run on your local machine and use the standard input and output streams (stdio) for communication between services on the same device.

Remote MCP servers

Run on the service's infrastructure and offer an HTTP endpoint to AI applications for communication between the AI MCP client and the MCP server. For more information about MCP architecture, see MCP architecture.

Google and Google Cloud remote MCP servers

Google and Google Cloud remote MCP servers have the following features and benefits:

• Simplified, centralized discovery
• Managed global or regional HTTP endpoints
• Fine-grained authorization
• Optional prompt and response security with Model Armor protection
• Centralized audit logging

For information about other MCP servers and information about security and governance controls available for Google Cloud MCP servers, see Google Cloud MCP servers overview.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

1. Enable the Agent Retrieval API.

   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

Required roles

To get the permissions that you need to use the Agent Retrieval MCP server, ask your administrator to grant you the following IAM roles on the project where you want to use the Agent Retrieval MCP server:

• Make MCP tool calls: MCP Tool User (roles/mcp.toolUser)
• Read Agent Retrieval resources: Vector Search Viewer (roles/vectorsearch.viewer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to use the Agent Retrieval MCP server. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to use the Agent Retrieval MCP server:

• Make MCP tool calls: mcp.tools.call
• List and inspect collections and indexes: vectorsearch.collections.list, vectorsearch.collections.get, vectorsearch.indexes.list, vectorsearch.indexes.get
• Read and search data objects: vectorsearch.dataObjects.get, vectorsearch.dataObjects.query, vectorsearch.dataObjects.search

You might also be able to get these permissions with custom roles or other predefined roles.

The Agent Retrieval MCP server exposes only read-only tools; no write permissions are required.

Authentication and authorization

The Agent Retrieval MCP server uses the OAuth 2.0 protocol with IAM for authentication and authorization. All Google Cloud identities are supported for authentication to MCP servers.

We recommend that you create a separate identity for agents that are using MCP tools so that access to resources can be controlled and monitored. For more information about authentication, see Authenticate to MCP servers.

Agent Retrieval MCP OAuth scopes

OAuth 2.0 uses scopes and credentials to determine if an authenticated principal is authorized to take a specific action on a resource. For more information about OAuth 2.0 scopes at Google, see Using OAuth 2.0 to access Google APIs.

The Agent Retrieval MCP server accepts the following OAuth scope:

Scope URI	Description
https://www.googleapis.com/auth/cloud-platform	Grants broad access to all Google Cloud services, including all Agent Retrieval features.

Configure an MCP client to use the Agent Retrieval MCP server

AI applications and agents, such as Claude or Antigravity, can instantiate an MCP client that connects to a single MCP server. An AI application can have multiple clients that connect to different MCP servers. If your application isn't listed in the client-specific guidance, then you can use the following information to connect from most applications.

In your AI application, look for a way to add or connect to a remote MCP server. For the Agent Retrieval MCP server, enter the following information as required:

• Server name: Agent Retrieval MCP server

• Server URL or Endpoint: https://vectorsearch.googleapis.com/mcp

  This single endpoint exposes all nine Agent Retrieval MCP tools. Tool calls are dispatched to the correct backend by header-based routing.

• Transport: HTTP

• Authentication details: your Google Cloud credentials, your OAuth Client ID and secret, or an agent identity and credentials. For more information about authentication, see Authenticate to MCP servers.

Header-based routing and client protocol requirements

The Agent Retrieval MCP server dispatches every tools/call at the network edge based on two HTTP headers:

• Mcp-Name — must equal the tool name in the request body (params.name).
• Mcp-Param-Region — must equal the location component of the resource path in the request body (for example, us-central1 for a Collection at projects/PROJECT_ID/locations/us-central1/collections/COLLECTION_ID).

If either header is missing or does not match the body, the request is rejected with HTTP 400 Bad Request.

Your MCP client must emit these headers dynamically per tools/call. This behavior is standardized in MCP protocol version 2026-07-28 and later; make sure your MCP client library advertises at least this protocol version during the initialize handshake. Clients pinned to earlier protocol versions, or SDK versions that don't support dynamic header emission, cannot use the Agent Retrieval MCP server through the unified /mcp endpoint.

Redirect URIs

For web-based applications, and some desktop applications, you must allowlist a redirect URI when you create a client ID and secret for authentication. Redirect URIs are used by the authorization server to send tokens to your application. Your application's documentation should specify the redirect URI that you must use. Custom redirect URIs aren't supported.

For application-specific guidance about setting up and connecting to MCP server, see Client-specific guidance.

For more general guidance, see the following resources:

• Connect to remote MCP servers.
• Configure MCP in an AI application.

Available tools

The Agent Retrieval MCP server exposes nine read-only tools:

Tool	Description
list_collections	List Agent Retrieval collections in a project and location.
get_collection	Retrieve the schema and metadata of a specific collection.
list_indexes	List indexes defined on a collection.
get_index	Retrieve the configuration of a specific index.
get_data_object	Retrieve a data object by ID from a collection.
search_data_objects	Run a vector, semantic, or text search against a collection.
query_data_objects	List data objects that match a filter expression.
batch_search_data_objects	Run multiple searches in parallel and fuse the results with Reciprocal Rank Fusion (RRF) or the Vertex Ranking API.
aggregate_data_objects	Aggregate data objects that match a filter expression (for example, counts).

All tools are read-only; the MCP server does not expose any write, update, or delete operations on Agent Retrieval resources.

List tools

Use the MCP inspector to list tools, or send a tools/list HTTP request directly to the Agent Retrieval MCP server. The tools/list method doesn't require authentication.

The Agent Retrieval MCP server uses the MCP 2026-07-28 stateless protocol, so each request is self-describing and must declare the protocol version in both the MCP-Protocol-Version HTTP header and the _meta.io.modelcontextprotocol/protocolVersion body field. The Mcp-Method HTTP header must also match the method in the body.

curl -X POST 'https://vectorsearch.googleapis.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28"
      }
    }
  }'

Sample use cases

The following are sample use cases for the Agent Retrieval MCP server:

• Resource inspection: list collections and indexes in a project, and inspect their schemas and metadata.
• Vector and semantic search: run vector or semantic search against a collection to find the most relevant data objects for a query.
• Hybrid retrieval: combine semantic, text, and vector searches in a single batch call and fuse the results with Reciprocal Rank Fusion (RRF) or the Vertex Ranking API.
• Data object retrieval: retrieve individual data objects by ID, or query a collection by filter to inspect ingested records.

Sample prompts

• "List the Agent Retrieval collections in project PROJECT_ID in REGION."
• "Show the schema of collection COLLECTION_ID in region REGION."
• "Run a semantic search on collection COLLECTION_ID for QUERY_TEXT and return the top 5 nearest neighbors."
• "Do a hybrid search on collection COLLECTION_ID for QUERY_TEXT that combines semantic and text search, then rerank the top 50 with semantic-ranker-fast@latest."
• "Get the data object with ID DATA_OBJECT_ID from collection COLLECTION_ID."

In the prompts, replace the following:

• PROJECT_ID: the Google Cloud project ID
• REGION: the region of your collection (for example, us-central1)
• COLLECTION_ID: the ID of the Agent Retrieval collection
• DATA_OBJECT_ID: the ID of a data object in the collection
• QUERY_TEXT: the natural-language text of the query

Quotas and limits

The Agent Retrieval MCP server doesn't have its own quotas. There is no limit on the number of calls that can be made to the MCP server. You are still subject to the quotas enforced by the Agent Retrieval API, which the MCP server tools call on your behalf. For more information, see Agent Retrieval quotas.

What's next

• Learn how to create a Collection.
• Learn how to search for data objects.
• Learn how to rerank search results.
• Learn more about Google Cloud MCP servers.