Host MCP servers on Cloud Run

This guide shows how to host a Model Context Protocol (MCP) server with streamable HTTP transport on Cloud Run, and provides guidance for authenticating MCP clients.

MCP is an open protocol that standardizes how AI agents interact with their environment. The AI agent hosts an MCP client, and the tools and resources it interacts with are MCP servers. The MCP client can communicate with the MCP server over two distinct transport types:

You can host MCP clients and servers on the same local machine, host an MCP client locally and have it communicate with remote MCP servers hosted on a cloud platform like Cloud Run, or host both the MCP client and server on a cloud platform.

Cloud Run supports hosting MCP servers with streamable HTTP transport, but not MCP servers with stdio transport.

Before you begin

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

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

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Set up your Cloud Run development environment in your Google Cloud project.
  7. Ensure you have the appropriate permissions to deploy services, and the Cloud Run Admin (roles/run.admin) and Service Account User (roles/iam.serviceAccountUser) roles granted to your account.

    8. Learn how to grant the roles

    Console

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the Google Account email address that is used to deploy the Cloud Run service.

    5. In the Select a role list, select a role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

    gcloud

    To grant the required IAM roles to your account on your project:

       gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL \
       --role=ROLE

    Replace:

    • PROJECT_NUMBER with your Google Cloud project number.
    • PROJECT_ID with your Google Cloud project ID.
    • PRINCIPAL with the account you are adding the binding for. This is typically the Google Account email address that is used to deploy the Cloud Run service.
    • ROLE with the role you are adding to the deployer account.

Host remote streamable HTTP MCP servers

MCP servers that use the streamable HTTP transport can be hosted remotely from their MCP clients. When hosting this type of MCP server on Cloud Run, you can either specify a container image to deploy, or deploy your source code directly.

Container deployment

Any container image that adheres to Cloud Run's Container runtime contract can be deployed to a Cloud Run service.

If the MCP servers are already offered as container images hosted on Docker Hub, these can be deployed using the following gcloud CLI command:

gcloud run deploy --image IMAGE

Replace IMAGE with the container image URL.

Source deployment

Deploy from source automatically builds a container image from source code and deploys it.

MCP servers that are written in a programming language of your choice can be deployed from source using the following gcloud CLI command:

gcloud run deploy --source .

After you deploy your HTTP MCP server to Cloud Run, the MCP server gets a HTTPS URL and communication can use Cloud Run's built in support for HTTP response streaming.

Authenticate MCP clients

Depending on where you hosted the MCP client, see the section that is relevant for you:

Authenticate local MCP clients

If the AI agent hosting the MCP client runs on a local machine, use one of the following methods to authenticate the MCP client:

For more information, refer to the MCP specification on Authentication.

IAM invoker permission

By default, the URL of Cloud Run services requires all requests to be authorized with the Cloud Run Invoker (roles/run.invoker) IAM role. This IAM policy binding ensures that a strong security mechanism is used to authenticate your local MCP client.

After deploying your MCP server to a Cloud Run service in a region, run the Cloud Run proxy on your local machine to securely expose the remote MCP server to your client using your own credentials:

gcloud run services proxy MCP_SERVER_NAME --region REGION --port=3000

Replace:

  • MCP_SERVER_NAME with the name of your Cloud Run service.
  • REGION with the Google Cloud region where you deployed your service. For example, europe-west1.

The Cloud Run proxy command creates a local proxy on port 3000 that forwards requests to the remote MCP server and injects your identity.

Update the MCP configuration file of your MCP client with the following:

{
  "mcpServers": {
    "cloud-run": {
      "url": "http://localhost:3000/sse"
    }
  }
}

If your MCP client does not support the url attribute, use the mcp-remote npm package:

{
  "mcpServers": {
    "cloud-run": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/sse"
      ]
    }
  }
}

OIDC ID token

Depending on whether the MCP client exposes headers or uses a way of providing a custom authenticated transport, you might consider authenticating the MCP client with an OIDC ID token.

You can use various Google authentication libraries to get an ID token from the runtime environment, for example the Google Auth Library for Python. This token must have the correct audience claim that matches the receiving service's *.run.app URL, unless you use custom audiences. You must also include the ID token in client requests, such as Authorization: Bearer <token value>.

If the MCP client does not expose either headers or transport, use a different authentication method.

Authenticate MCP clients running on Cloud Run

If the AI agent hosting the MCP client runs on Cloud Run, use one of the following methods to authenticate the MCP client:

Deploy the MCP server as a sidecar

The MCP server can be deployed as a sidecar where the MCP client runs.

No specific authentication is required for this use case, since the MCP client and MCP server are on the same instance. The client can connect to the MCP server using a port on http://localhost:PORT. Replace PORT with a different port than the one used to send requests to the Cloud Run service.

Authenticate service to service

If the MCP server and MCP client run as distinct Cloud Run services, see Authenticating service-to-service.

Use Cloud Service Mesh

An agent hosting an MCP client can connect to a remote MCP server using Cloud Service Mesh.

You can configure the MCP server service to have a short name on the mesh, and the MCP client can communicate to the MCP server using the short name http://mcp-server. Authentication is managed by the mesh.

What's next