Google Tag Manager (noscript) End Google Tag Manager (noscript) HTML How to securely connect internal Cloud Run MCP servers to Gemini Enterprise NOV. 20, 2026 Neeraj Agrawal Forward Deployed Engineer Google Cloud header_image_1600x900

Enterprise teams adopting Gemini Enterprise are increasingly building custom Model Context Protocol (MCP) servers to connect AI agents with internal APIs, databases, and business workflows. Google Cloud Run is a natural fit for hosting these lightweight StreamableHTTP MCP servers: it scales automatically, manages TLS certificates out of the box, and integrates natively with Cloud IAM.

However, moving a custom MCP server from an initial prototype to an enterprise production environment immediately introduces three real-world security and networking challenges:

  1. No public internet exposure (internal-only ingress): Enterprise security policies require internal MCP servers to block all public internet traffic and accept requests only from private Virtual Private Cloud (VPC) networks. When internal ingress is enabled on Cloud Run, default public calls from Gemini Enterprise are rejected at Google's edge with HTTP 404.
  2. Service and user authentication (Cloud Run IAM + OAuth 2.0): Production deployments require two independent identity checks on every tool call. Cloud Run IAM must verify that the network request originated from your authorized Gemini Enterprise instance, and your MCP application code must validate the signed-in human user's OAuth 2.0 access token before acting on their behalf.
  3. Shared VPC scale without DNS collisions: Large enterprises often run hundreds of Cloud Run services across a centralized Shared (Hub) VPC. Overriding the entire *.run.app domain in Private Cloud DNS for a single MCP server can hijack DNS resolution and break routing for other Cloud Run services across that network.

Here is how you can solve all three challenges using Egress Agent Gateway, Private Service Connect (PSC), and FQDN-scoped Private Cloud DNS, complete with a runnable reference implementation and setup scripts on GitHub.


How the private path works

Connecting Gemini Enterprise (which runs in a Google-managed tenant project) to an internal serverless Cloud Run MCP server requires bridging two network hops and one scoped DNS lookup:

architecture Figure 1: Private VPC and dual-header authentication architecture for connecting Gemini Enterprise to internal Cloud Run MCP servers.

Three Google Cloud networking and identity mechanisms work together in this architecture:

1. Two-bridge private VPC routing (PSC Network Attachment + PGA or PSC for Google APIs)

Unlike a Compute Engine VM with an internal IP address inside your subnet, Cloud Run is serverless. Private routing therefore uses two bridges:

  • Bridge 1 (Into your VPC via PSC Network Attachment): A regional Egress Agent Gateway in Agent-to-Anywhere mode connects to a PSC Network Attachment in your regional subnet (us-central1 or europe-west1). This places a managed network interface inside your VPC without public IPs or inbound firewall rules.
  • Bridge 2 (From your VPC to Serverless Cloud Run): Once the packet enters your VPC subnet, it must reach Google's serverless Cloud Run frontend privately so Cloud Run recognizes the source VPC and satisfies internal ingress rules. Depending on your enterprise VPC design, you can use either:
    • Option A: Subnet Private Google Access (199.36.153.8/30): Uses Google's built-in Private Google Access virtual IPs with zero extra VPC endpoints (recommended for standard VPCs that retain the default 0.0.0.0/0 route to the default internet gateway).
    • Option B: Global PSC Endpoint for Google APIs (240.0.0.10): Uses a global internal IP address and forwarding rule targeting Google's built-in all-apis bundle (which includes Cloud Run with no internal load balancer or service attachment needed on the Cloud Run side). Google Cloud automatically injects a dedicated /32 internal route into your VPC, so private Cloud Run routing works even in locked-down VPCs where the 0.0.0.0/0 default internet route is deleted.
vpc-routing-options-table

2. FQDN-scoped Private Cloud DNS resolution (safe for Shared VPCs)

When the Egress Agent Gateway receives a tool call for your Cloud Run MCP server URL, it resolves the hostname once before injecting the packet into your VPC. Without Private Cloud DNS, public DNS resolves .run.app domains to public internet IPs, which time out (HTTP 502) because a PSC Network Attachment does not route out to the public internet.

Instead of creating a wildcard *.run.app private zone, which would override DNS resolution for every Cloud Run service in a Shared VPC, you create a Private Cloud DNS zone scoped exclusively to your MCP service's exact fully qualified domain name (FQDN) and peer only that domain with the Agent Gateway. Because Cloud DNS uses longest-suffix matching, every other Cloud Run service in your Shared VPC continues resolving normally. Meanwhile, the Agent Gateway opens its HTTPS connection to the private VIP (199.36.153.8 or 240.0.0.10) while preserving your Cloud Run service hostname in the TLS SNI and HTTP Host header so Cloud Run routes the request to your exact container.

3. Dual-header service and user identity

When connecting to a Cloud Run MCP server URL, Gemini Enterprise sends two distinct authorization headers on every request:

  • Infrastructure layer (X-Serverless-Authorization header): Contains a Google-signed OIDC ID token for your project's Gemini Enterprise service agent. Cloud Run IAM verifies this token against the Cloud Run Invoker role at the serverless edge and strips the header before the request reaches your container.
  • Application layer (Authorization Bearer header): Contains the signed-in user's OAuth 2.0 access token untouched, allowing middleware inside your MCP server to verify the caller's identity and enforce per-user permissions.
class OAuth2ValidationMiddleware(BaseHTTPMiddleware):
  """Validates the end-user OAuth 2.0 Bearer token on incoming MCP requests."""

  async def dispatch(self, request: Request, call_next) -> Response:
    if request.url.path == "/health":
      return await call_next(request)

    has_serverless_auth = "x-serverless-authorization" in request.headers
    auth_header = request.headers.get("authorization", "")

    if auth_header.lower().startswith("bearer "):
      raw_token = auth_header.split(" ", 1)[1].strip()
      verified = await _verify_google_oauth_token(raw_token)
      if verified is None and REQUIRE_OAUTH:
        return JSONResponse(
            {"error": "Invalid or expired OAuth 2.0 Bearer token."},
            status_code=401,
        )
    elif REQUIRE_OAUTH:
      return JSONResponse(
          {"error": "Missing Authorization: Bearer <token> header."},
          status_code=401,
      )
    return await call_next(request)
Python Copied

5 steps to configure the integration

Our companion GitHub repository automates the entire deployment into sequential setup scripts alongside step-by-step Cloud Console instructions:

Step 1: Lock down Cloud Run and grant service invoker access

Deploy your StreamableHTTP MCP server to Cloud Run with internal-only ingress and IAM authentication enabled, and grant the Cloud Run Invoker role to your project's Gemini Enterprise service agent so only your Gemini Enterprise instance can invoke the container.

Step 2: Provision the VPC, PSC Network Attachment, and Egress Agent Gateway

Enable Private Google Access on your regional VPC subnet and create a Private Service Connect Network Attachment set to accept connections automatically. Next, create a Google-managed Egress Agent Gateway in Agent-to-Anywhere mode, grant networking and DNS peering permissions to the auto-created gateway service accounts, attach your network attachment, and apply an outbound authorization policy.

Step 3: Configure FQDN-scoped Private Cloud DNS and DNS peering

In Cloud DNS, create a private managed zone attached to your VPC for only your MCP service's exact Cloud Run hostname. Point its A record to Google's Private Google Access VIPs (or to your internal PSC endpoint IP for isolated VPCs without a default internet route), and configure DNS peering on the Agent Gateway for that single hostname.

Step 4: Bind the Agent Gateway and register the MCP server in Gemini Enterprise

In the Gemini Enterprise console under Security Configuration, bind your Egress Agent Gateway to your app. Register your Custom MCP Server data store with your Cloud Run endpoint and OAuth 2.0 client credentials, and enable Agent Gateway egress and Actions mode on the connector.

Step 5: Verify private MCP calls in Cloud Logging

Reload your custom actions in the console and run a test prompt in the Gemini Enterprise web app. In Cloud Logging, you can verify that tool initialization, discovery, and execution calls route privately through the Egress Agent Gateway to your internal Cloud Run container with both service IAM and user OAuth 2.0 checks passing.

Next steps

To deploy and test both private routing patterns in your own Google Cloud project, check out the GitHub repository for:

  • A complete Python StreamableHTTP Cloud Run MCP server with OAuth 2.0 validation middleware, Dockerfile, and local smoke tests.
  • Step-by-step setup scripts and Cloud Console UI instructions covering both Option A (Subnet Private Google Access) and Option B (Global PSC Endpoint for Google APIs), including Shared VPC IAM bindings and Cloud Logging verification.

Related documentation

posted in: Previous Next Related Posts Multi-Turn Agentic Reinforcement Learning with Tunix and Gemma 4 on Google TPUs AI Cloud Tutorials Learn

Multi-Turn Agentic Reinforcement Learning with Tunix and Gemma 4 on Google TPUs

NOV. 19, 2026
How to handle user, connector, and agent auth in Gemini Enterprise with a custom UI Cloud Learn Explore

How to handle user, connector, and agent auth in Gemini Enterprise with a custom UI

NOV. 20, 2026
Agent Anomaly Detection: Safeguarding agents across other clouds AI Cloud Announcements

Agent Anomaly Detection: Safeguarding agents across other clouds

NOV. 20, 2026