Host MCP servers on Cloud Run

This guide shows how to host aModel Context Protocol (MCP) server withstreamable HTTP transport on Cloud Run, and provides guidancefor authenticating MCP clients. If you're new to MCP, read the followingresources:

MCP is an open protocol that standardizes how AI agents interact with theirenvironment. The AI agent hosts anMCP client, and the tools and resources itinteracts with areMCP servers. The MCP client can communicate with the MCPserver over two distinct transport types:

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

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

The following diagram shows how the MCP client takes the AI agent's intent andsends a standardized request to MCP servers, specifying the tool to be executed.After the MCP server executes the action and retrieves the results, the MCPserver returns the result back to the MCP client in a consistent format.

An MCP server interacts with an AI agent through an MCP client.
Figure 1.The MCP server hosted on Cloud Run interacts with the MCP client, which interacts with the AI agent.

The guidance on this page applies if you are developing your own MCP server orif you are using an existing MCP server.

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.

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

  3. Verify 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.

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

  5. Verify that billing is enabled for your Google Cloud project.

  6. Set up your Cloud Run development environmentin your Google Cloud project.
  7. Ensure you have the appropriatepermissions to deploy services, and theCloud Run Admin (roles/run.admin) andService 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 theIAM page.

      Go to IAM
    2. Select the project.
    3. ClickGrant access.

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

    5. In theSelect a role list, select a role.
    6. To grant additional roles, clickAdd another role and add each additional role.
    7. ClickSave.

    gcloud

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

    gcloudprojectsadd-iam-policy-bindingPROJECT_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 email address that is used to deploy the Cloud Run service.
    • ROLE with the role you are adding to the deployer account.

Host remote SSE or streamable HTTP MCP servers

MCP servers that use the Server-sent events (SSE) or streamable HTTP transportcan be hosted remotely from their MCP clients.

To deploy this type of MCP server to Cloud Run, you can deploythe MCP server as a container image or as source code (commonly Node.js orPython), depending on how the MCP server is packaged.

Container images

Remote MCP servers distributed as container images are web servers that listenfor HTTP requests on a specific port, which means they adhere toCloud Run'scontainer runtime contractand can be deployed to a Cloud Run service.

To deploy an MCP server packaged as a container image, you need to have theURL of the container image and the port on which it expects to receiverequests. These can bedeployed using the followinggcloud CLI command:

gcloudrundeploy--imageIMAGE_URL--portPORT

Replace:

  • IMAGE_URL with the container image URL, forexampleus-docker.pkg.dev/cloudrun/container/mcp.
  • PORT with the port it listens on, for example3000.

Sources

Remote MCP servers that are not provided as container images can bedeployed to Cloud Runfrom their sources,notably if they are written in Node.js or Python.

  1. Clone the Git repository of the MCP server:

    gitclonehttps://github.com/ORGANIZATION/REPOSITORY.git

  2. Navigate to the root of the MCP server:

    cdREPOSITORY

  3. Deploy to Cloud Run with the following gcloud CLI command:

    gcloudrundeploy--source.

After you deploy your HTTP MCP server to Cloud Run, the MCPserver gets aHTTPS URL andcommunication can use Cloud Run's built in support for HTTPresponse streaming.

Authenticate MCP clients for AI agents

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

Authenticate local MCP clients

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

For more information, refer to theMCP specification on Authentication.

IAM invoker permission

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

After deploying your MCP server to a Cloud Run service in aregion, run theCloud Run proxy onyour local machine to securely expose the remote MCP server to your client usingyour own credentials:

gcloudrunservicesproxyMCP_SERVER_NAME--regionREGION--port=3000

Replace:

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

The Cloud Run proxy command creates a local proxy on port3000that 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 theurl attribute, use themcp-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 acustom authenticated transport, you might consider authenticating the MCP clientwith anOIDC ID token.

You can use various Google authentication libraries to get an ID token from theruntime environment, for example theGoogle Auth Library for Python.This token must have the correct audience claim that matches the receivingservice's*.run.app URL, unless you usecustom audiences. You must alsoinclude the ID token in client requests, such asAuthorization: Bearer <token value>.

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

Authenticate MCP clients running on Cloud Run

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

Deploy the MCP server as a sidecar

The MCP server can bedeployed as a sidecarwhere the MCP client runs.

No specific authentication is required for this use case, since the MCP clientand MCP server are on the same instance. The client can connect to the MCPserver using a port onhttp://localhost:PORT. ReplacePORT with a different port than the one used to sendrequests to the Cloud Run service.

Authenticate service to service

If the MCP server and MCP client run as distinct Cloud Runservices, seeAuthenticating service-to-service.

Use Cloud Service Mesh

An agent hosting an MCP client can connect to a remote MCP server usingCloud Service Mesh.Using a service mesh simplifies the orchestration of microservices by handlingauthentication and traffic management automatically.

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

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.