> [!IMPORTANT]
> **Key Term:** In Gemini Enterprise, the term *data store* can be used interchangeably with the term *connector* or *data connector*.

> [!IMPORTANT]
> **Key Term:** In the Model Context Protocol (MCP) specification, capabilities are called *tools*. In Gemini Enterprise data stores, these tools are referred to as *actions*. The two terms can be used interchangeably.

This page explains how to connect your data sources using a custom Model Context
Protocol (MCP) server, letting Gemini Enterprise securely access your company's
private data.

## Overview

The custom MCP data store lets you integrate public and private tools, as well
as MCP-compliant third-party systems, directly into Gemini Enterprise. This
approach provides a unified method to connect legacy systems when standard
connectors are unavailable. With this integration, your AI agents can access
business-critical information and specialized logic within your infrastructure.

Access to public MCP servers is routed through the Google-managed network. To
enable Agent Gateway egress to your private network, the custom MCP
server must be registered within your Gemini Enterprise app and configured
to route private traffic through Agent Gateway (supported in
`us-central1` and `europe-west1`).

## Limitations

The custom MCP server has the following limitations:

- **Server-Sent Events (SSE)** : The older `SSE` transport isn't supported. The
  connector exclusively supports the newer `StreamableHTTP` transport.

- **TLS certificate requirement**: Configure custom MCP servers with a TLS
  certificate signed by a publicly trusted Certificate Authority (CA), with
  the following exception:

  - **Private MCP servers with Agent Gateway** : If you route egress traffic through Agent Gateway, you can use private CAs or self-signed certificates by configuring custom TLS trust anchors (`tlsConfig`) in your [agent connectivity
    template](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-vpc-connectivity#tls-certificate-requirements).
- **Actions limit** : To ensure optimal performance, limit the number of enabled
  actions in your custom MCP server data store to 100 at a time. For more
  information, see [Enable actions](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-custom-mcp-server.md.txt#enable-actions).

- **Agent Gateway binding limit**: A Gemini Enterprise app binds to a single
  egress Agent Gateway, but multiple Gemini Enterprise apps
  can share the same Agent Gateway.

- **App-scoped creation** : You can't link a standalone Custom MCP server data
  store to a Gemini Enterprise app. Create the data store directly within
  your app under **Connected Data Stores**.

- **VPC Service Controls** : Egress controls are enforced through organization
  policy constraints, such as `allowedEgressFqdns` and `allowedDataSources`,
  rather than runtime traffic enforcement. Custom MCP servers are supported in
  VPC Service Controls-enabled projects when you explicitly allow the required
  egress domains and data sources. For more information, see
  [Override the organization policy for Custom MCP data stores](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/override-constraint-for-custom-mcp-data-stores.md.txt).

## Before you begin

Before you set up your custom MCP server connection, ensure you perform the
following:

- Several organization policy constraints apply to Custom MCP data stores. You
  must:

  - Override the organization policy constraint that blocks Custom MCP
    data store creation. For more information, see
    [Override the organization policy for Custom MCP data stores](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/override-constraint-for-custom-mcp-data-stores.md.txt).

  - Explicitly allow the fully qualified domain names (FQDNs) for your custom
    MCP server URL, authorization URL, and token URL. For more information, see
    [Configure allowed egress FQDNs](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/configure-allowed-egress-fqdns.md.txt).

    > [!NOTE]
    > **Note:** You only need to add the domain name, not the full URL. For example, for an MCP server URL of `https://api.cymbal.com/mcp` with authorization and token URLs on `auth.cymbal.com`, allow both `api.cymbal.com` and `auth.cymbal.com`.

  - If project enforcement is enabled or the project is VPC Service Controls-protected,
    you must add `custom_mcp` to the allowed data sources. See
    [Configure allowed data sources](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/configure-allowed-data-sources.md.txt).

  - If you route egress traffic through Agent Gateway, ensure
    your project organization policy permits binding your
    Gemini Enterprise app to the gateway. For more information, see
    [Restrict Gemini Enterprise binding to approved Agent Gateways](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-ge-deploy.md.txt#restrict-ge).

- Optional: If your custom MCP server is hosted inside a private
  Virtual Private Cloud (VPC) network, complete the prerequisite network
  attachment, gateway, and firewall configurations. For details, see
  [Prerequisites to set up a custom MCP server data store with VPC connectivity](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-vpc-custom-mcp-server.md.txt).

- Grant the **Discovery Engine Editor** role
  (`roles/discoveryengine.editor`). This role is required for your
  administrator to create the data store.

  To grant this role, do the following:
  1. In the Google Cloud console, go to the **IAM** page.

     [Go
     to IAM](https://console.cloud.google.com/iam-admin/iam)
  2. Locate the user account, and click the edit **Edit** icon.

  3. Grant the **Discovery Engine Editor** role to your
     user. For more information, see [IAM
     roles and permissions](https://cloud.google.com/gemini/enterprise/docs/access-control).

- Register Gemini Enterprise as an OAuth client application with your identity
  provider (for example, Okta, Azure AD, or Google).

  To register the app, do the following:
  1. Set the authorization redirect URL to
     `https://vertexaisearch.cloud.google.com/oauth-redirect`.

  2. Grant necessary OAuth scopes to the client app.

  After you register the client app, obtain the `client_id` and `client_secret`
  that are needed for configuring the custom MCP server data store in the
  following steps.
- If your custom MCP server is hosted on Cloud Run and requires
  authentication, grant the **Cloud Run Invoker** (`roles/run.invoker`) role to
  the service agent. For more information, see
  [Set up authentication for a custom MCP server on Cloud Run](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-custom-mcp-server.md.txt#cloud_run_authentication).

## Set up authentication for a custom MCP server on Cloud Run

If your custom MCP server is hosted on Cloud Run and requires
authentication, Gemini Enterprise can securely connect to private services
that don't allow public access.

### How authentication works

When you connect to a Cloud Run service, Gemini Enterprise automatically sends the following authorization headers in each request:

- **`X-Serverless-Authorization`**: Contains a Google-signed ID token that authenticates the Gemini Enterprise service agent.
- **`Authorization`**: Preserves the user's OAuth token intact.

> [!NOTE]
> **Note** : Gemini Enterprise automatically sends the Google-signed ID token only when you connect to a default Cloud Run URL that ends in `.run.app`. Gemini Enterprise doesn't send the ID token if your service uses a custom domain.

### Grant access to the service agent

To authorize Gemini Enterprise to invoke your private Cloud Run
service, grant the **Cloud Run Invoker** (`roles/run.invoker`) role to the
Gemini Enterprise service agent on the receiving service.

The service agent email uses the following format: `
service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com
`

Replace `PROJECT_NUMBER` with the project number of the
Google Cloud project that hosts your Gemini Enterprise app.

For instructions on how to grant IAM roles on a service, see
[Authenticating service-to-service](https://docs.cloud.google.com/run/docs/authenticating/service-to-service.md.txt).

## Create the custom MCP server data store

> [!NOTE]
> **Note:** By default, outbound traffic to your custom MCP server doesn't route through [Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-ge-deploy.md.txt) unless you select **Route egress through Agent Gateway** on the **MCP Server
> Configuration** page.

To set up the configuration flow, follow these steps:

1. In the Google Cloud console, go to the **Gemini Enterprise** page.

   [Gemini Enterprise](https://console.cloud.google.com/gemini-enterprise/)
2. In the navigation menu, click **Apps**, and then select the app that requires
   custom MCP data store connectivity.

3. Click **Connected Data Stores**.

4. Click **New data
   store**.

5. On the **Select a data source** page, enter *Custom MCP Server* into the
   **Search sources** field. The **Custom MCP Server** card displays.

6. Click **Add MCP server** . The **MCP Server Configuration** page displays.

7. Optional: To route outbound traffic through Agent Gateway,
   select the **Route egress through Agent Gateway** checkbox. Select this
   option for either of the following scenarios:

   - **Private network hosting**: You host your custom MCP server privately inside a VPC network.
   - **Static IP egress**: You host your custom MCP server externally (such as on-premises or with a third-party provider) and require incoming requests to originate from reserved static IP addresses. Routing traffic through Agent Gateway into your VPC network lets you egress traffic through a gateway with fixed IP addresses, so you can configure IP-based firewall allowlists on your external server.

   > [!NOTE]
   > **Note:** This setting only routes tool calls sent to your custom MCP server through Agent Gateway. Other traffic, such as AI model processing and document search, doesn't pass through the gateway. If you leave this checkbox unselected, Gemini Enterprise connects to your MCP server directly over the public internet.

   In the **Engine resource name** field, enter the resource name of the engine
   that egress traffic routes to in the following format:

       projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID

   Replace the following:
   - `PROJECT_NUMBER`: Your Google Cloud project number.
   - `LOCATION`: The location of your app, such as `global`, `us`, or `eu`.
   - `APP_ID`: The ID of your app.

   ### How to obtain your engine resource name

   If you don't know your app's engine resource name, you can list the engines in your project using the Discovery Engine API:

   ```bash
   curl -s -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines" \
   | jq -r '.engines[]? | "App Name: \(.displayName)\nEngine Resource Name: \(.name)\n"'
   ```

   Replace the following:
   - `PROJECT_ID`: the ID of your project.
   - `ENDPOINT_LOCATION`: the multi-region for your API request. Specify one of the following values:
     - `us` for the US multi-region
     - `eu` for the EU multi-region
     - `global` for the Global location

     For more information, see [Specify a multi-region
     for your data store](https://docs.cloud.google.com/gemini/enterprise/docs/locations#specify_a_multi-region_for_your_data_store).
   - `PROJECT_NUMBER`: the number of your Google Cloud project.
   - `LOCATION`: the location of your app (such as `global`, `us`, or `eu`).

   Example output:

   ```
   App Name: Cymbal Math App
   Engine Resource Name: projects/1234567890/locations/global/collections/default_collection/engines/chat-app-cymbal
   ```

   For more information, see [`projects.locations.collections.engines.list`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/projects.locations.collections.engines/list.md.txt).
8. In the **Authentication settings** section, select one of the following
   options:

   - **OAuth 2.0**: Select this option to add authentication.

     1. Enter the values in the following required fields:

        | Field | Description |
        |---|---|
        | **MCP Server URL** | This is the endpoint where your MCP server is hosted. It must be an HTTPS URL. Gemini Enterprise only supports the `StreamableHTTP` transport. The URL often ends with `/mcp`. For example, `https://mcp.cymbal.com/mcp`. > [!NOTE] > **Note** : If your server is hosted on Cloud Run, enter your default service URL ending in `.run.app`. Gemini Enterprise automatically sends a Google-signed ID token for IAM authentication. |
        | **Authorization URL** | The base URL for the user to authorize Gemini Enterprise to access your MCP server. For example, `https://mcp.cymbal.com/authorize`. > [!NOTE] > **Note** : Enter only the base URL, without query parameters. Gemini Enterprise automatically appends standard OAuth parameters (such as `client_id`, `redirect_uri`, and `scope`) during authorization. If your authorization server requires additional parameters, specify them in the **Authorization URL Parameters** field. |
        | **Authorization URL Parameters** | Optional. Any additional parameters required by your authorization URL. For example, to get a refresh token from a Google MCP server, enter `&access_type=offline&prompt=consent`. <br /> If your authorization server requires an `audience` parameter, you can add it as a parameter in this setting. For example, `&audience=https://api.cymbal.com/v1/`. |
        | **Token URL** | The endpoint used to exchange the authorization code for an access token during OAuth authentication. For example, `https://mcp.cymbal.com/token`. |
        | **Client ID** | The unique identifier of the OAuth app that you registered in your identity provider to represent Gemini Enterprise. |
        | **Client Secret** | The confidential key associated with the OAuth app that you registered in your identity provider to represent Gemini Enterprise. |
        | **Scopes** | The permissions that define what actions Gemini Enterprise can perform on behalf of a user, or what data it can access on the MCP server. Gemini Enterprise requests these scopes during user authorization. Configure your OAuth app to support these scopes. <br /> When you specify scopes, consider the following: - Provide a space-separated list of scopes. For example, for Box, you provide: `root_readwrite manage_managed_users manage_groups`. - Ensure the scopes provided are sufficient to let the user sign in and use the tools or actions enabled by the administrator; otherwise, the agent can't access your app. - A common scope is `offline_access`, which lets the app request a refresh token. |
        | **Enable PKCE Support** | Optional. Select this checkbox to enable Proof Key for Code Exchange (PKCE, RFC 7636) for additional OAuth security. Enable this setting if your MCP server's OAuth provider supports PKCE. |
        | **Use HTTP Basic Authentication** | Optional. Selected by default. Sends the client ID and client secret in the HTTP `Authorization` header using Basic authentication instead of in the token request body. |

     2. Click **Verify Auth**.

     3. Click **Continue**.

   - **No authentication**: Select this option if your MCP server doesn't
     require authentication.

     1. Enter the **MCP Server URL** . This is the endpoint where your MCP
        server is hosted. It must be an HTTPS URL. Gemini Enterprise
        only supports the `StreamableHTTP` transport. The URL often ends
        with `/mcp`. For example, `https://mcp.cymbal.com/mcp`.

        > [!NOTE]
        > **Note** : If your server is hosted on Cloud Run, enter your default service URL ending in `.run.app`. Gemini Enterprise automatically sends a Google-signed ID token for IAM authentication.

     2. Click **Continue**.

9. Optional: In the **Advanced options** section, in the **MCP Server
   Description** field, describe what the MCP server does and how users can use
   it.

10. Click **Continue**.

11. In the **Configure your data connector** section, select the **Location of
    your data connector** from the **Multi-region** field list.

12. In the **Your data connector name** field, enter a name for your data store.

13. Optional: In the **Tag** field, enter a tag to uniquely identify this data
    connector across versions. This tag is immutable after you create it.

14. Optional: In the **Sensitive data protection policy** field, enter the
    resource path of a
    [Sensitive Data Protection content policy](https://docs.cloud.google.com/sensitive-data-protection/docs/content-policy.md.txt)
    to inspect and block sensitive data that Gemini Enterprise retrieves
    through this data store. Use the following format:
    `projects/PROJECT_ID/locations/LOCATION/contentPolicies/POLICY_ID`.

15. Click **Create** . Gemini Enterprise creates your data store and
    displays your data stores on the **Connected Data Stores** page.

    > [!NOTE]
    > **Note:** By default, no tools or actions from your custom MCP servers are enabled. You must enable the tools or actions. For more information, see [Enable actions](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-custom-mcp-server.md.txt#enable-actions).

### Verify the state of the custom MCP server

To verify the state of the custom MCP server, do the following:

1. Click your data store in the **Connected Data Stores** list. The details of
   your data store display.

2. Monitor the state of your data store until it changes to
   `Active`. After the state of your data store changes from `Creating`
   to `Active`, your custom MCP server data store is ready to be used.

## Enable actions

> [!IMPORTANT]
> **Key Term:** In the Model Context Protocol (MCP) specification, capabilities are called *tools*. In Gemini Enterprise data stores, these tools are referred to as *actions*. The two terms can be used interchangeably.

By default, all actions are turned off. When you connect an MCP server, all of
its tools are imported and displayed as actions in the Gemini Enterprise
data store. To ensure an
optimal experience, you can enable up to 100 actions at a time. To enable these
actions for your users, follow these steps:

1. Go to your custom MCP server data store.
2. Click **Actions \> Reload custom actions** to reauthenticate.

   > [!NOTE]
   > **Note:** This action performs a `tools/list` call on the MCP server to retrieve available tools, which are then displayed on the screen.

3. Select the actions to enable.

4. Click **Enable actions**.

### Configure annotations to skip user confirmation

When tools from your MCP server are imported as actions into the
Gemini Enterprise data store, Gemini Enterprise checks their tool annotations to
determine if user confirmation is required. By default, all calls to any
action require confirmation from the user, because Gemini Enterprise assumes
that any operation is potentially destructive and can mutate data.

If your server provides read-only functionality (such as querying a database)
and you want to skip this confirmation for a smoother user experience, you can
configure annotations in the specifications of your MCP tools before they are
imported as actions.

To manage user confirmation for data store actions, configure the following
annotations in your MCP tool definitions:

- `readOnlyHint`: Add this annotation to your tool definition if the operation is non-destructive and only reads data. The tool execution bypasses user confirmation.
- `destructiveHint`: Explicitly use this annotation if the tool modifies data. This maintains the default confirmation behavior.

<br />

For example, in Python:

<br />

```python
@mcp.tool(annotations={
       "destructiveHint": False,
       "readOnlyHint": True
   })
```

<br />

<br />

To ensure that your changes are reflected in your setup, reload custom actions.
For more information, see [Enable actions](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-custom-mcp-server.md.txt#enable-actions).

### Performance and reliability best practices

To minimize response latency and prevent request timeouts when using a custom
MCP server, follow these best practices:

- **Keep tool descriptions and schemas concise**: Keep tool descriptions and input parameter schemas concise to reduce prompt processing latency.
- **Use pagination or asynchronous polling for long-running operations**: Keep individual tool calls fast by paginating large query results. For long-running backend operations (such as large data warehouse queries or report generation), implement an asynchronous tool pattern where one tool starts the job and returns a job ID immediately, and a second tool polls the job status and retrieves the results.
- **Request offline access for persistent OAuth tokens** : When configuring OAuth 2.0 authentication, include the `offline_access` scope (or `&access_type=offline&prompt=consent` in **Authorization URL Parameters** for providers that require it) from initial setup so your identity provider issues a refresh token and requests don't fail or time out after the initial access token expires.
- **Turn off unused or unhealthy actions and data stores**: Only enable the actions that users need, and turn off custom MCP server data stores that are unused or undergoing maintenance so unreachable endpoints don't add latency to chat turns.

## What's next

- To protect against malicious inputs and outputs, enable Model Armor. For more information, see [Enable Model Armor](https://docs.cloud.google.com/gemini/enterprise/docs/enable-model-armor.md.txt).
- If you want to query your MCP server using a custom agent, instead of the Gemini Enterprise assistant, see [Create an agent](https://docs.cloud.google.com/gemini/enterprise/docs/workflow-builder/create-chat-agent.md.txt).
- To use your agent that's connected to your custom MCP server, see [Use an
  agent](https://docs.cloud.google.com/gemini/enterprise/docs/workflow-builder/use-chat-agent).
- To display source citation chips when Gemini Enterprise answers a question using tools on your custom MCP server, see [Configure citations for custom MCP data stores](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/configure-citations-for-custom-mcp-data-stores.md.txt).