Build and deploy a remote MCP Server on Cloud Run

This tutorial shows you how to build and deploy a remote Model Context Protocol (MCP) server on Cloud Run using the streamable HTTP transport. With streamable HTTP transport, the MCP server operates as an independent process that can handle multiple client connections.

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. Make sure 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. Grant the Cloud Run Invoker (roles/run.invoker) role to your account. This role allows the remote MCP server to access the Cloud Run service.

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 person_add Grant access.

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

5. In the Select a role list, select a role.
6. To grant additional roles, click add 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: your Google Cloud project number.
• PROJECT_ID: your Google Cloud project ID.
• PRINCIPAL: the email address of the account to which you are granting the role.
• ROLE: the role you are adding to the deployer account.

9. If you are under a domain restriction organization policy restricting unauthenticated invocations for your project, you will need to access your deployed service as described under Testing private services.

10. Install Uv, a Python package and project manager.

Prepare your Python project

The following steps describe how to set up your Python project with the uv package manager.

1. Create a folder named mcp-on-cloudrun to store the source code for deployment:

     mkdir mcp-on-cloudrun
     cd mcp-on-cloudrun
   

2. Create a Python project with the uv tool to generate a pyproject.toml file:

     uv init --name "mcp-on-cloudrun" --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.10
   

   The uv init command creates the following pyproject.toml file:

   [project]
   name = "mcp-server"
   version = "0.1.0"
   description = "Example of deploying an MCP server on Cloud Run"
   readme = "README.md"
   requires-python = ">=3.10"
   dependencies = []
   

3. Create the following additional new files:

   • server.py for the MCP server source code
   • test_server.py to test the remote server
   • A Dockerfile for deploying to Cloud Run

   touch server.py test_server.py Dockerfile
   

   Your project directory should contain the following structure:

   ├── mcp-on-cloudrun
   │   ├── pyproject.toml
   │   ├── server.py
   │   ├── test_server.py
   │   └── Dockerfile
   

Create an MCP server for math operations

To provide valuable context for improving the use of LLMs with MCP, set up a math MCP server with FastMCP. FastMCP provides a quick way to build MCP servers and clients with Python.

Follow these steps to create an MCP server for math operations such as addition and subtraction.

1. Run the following command to add FastMCP as a dependency in the pyproject.toml file:

   uv add fastmcp==2.8.0 --no-sync
   

2. Add the following math MCP server source code in the server.py file:

   import asyncio
   import logging
   import os
   
   from fastmcp import FastMCP 
   
   logger = logging.getLogger(__name__)
   logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)
   
   mcp = FastMCP("MCP Server on Cloud Run")
   
   @mcp.tool()
   def add(a: int, b: int) -> int:
       """Use this to add two numbers together.
   
       Args:
           a: The first number.
           b: The second number.
   
       Returns:
           The sum of the two numbers.
       """
       logger.info(f">>> 🛠️ Tool: 'add' called with numbers '{a}' and '{b}'")
       return a + b
   
   @mcp.tool()
   def subtract(a: int, b: int) -> int:
       """Use this to subtract two numbers.
   
       Args:
           a: The first number.
           b: The second number.
   
       Returns:
           The difference of the two numbers.
       """
       logger.info(f">>> 🛠️ Tool: 'subtract' called with numbers '{a}' and '{b}'")
       return a - b
   
   if __name__ == "__main__":
       logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}")
       # Could also use 'sse' transport, host="0.0.0.0" required for Cloud Run.
       asyncio.run(
           mcp.run_async(
               transport="streamable-http",
               host="0.0.0.0",
               port=os.getenv("PORT", 8080),
           )
       )
   

3. Include the following code in the Dockerfile to use the uv tool for running the server.py file:

   # Use the official Python image
   FROM python:3.13-slim
   
   # Install uv
   COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
   
   # Install the project into /app
   COPY . /app
   WORKDIR /app
   
   # Allow statements and log messages to immediately appear in the logs
   ENV PYTHONUNBUFFERED=1
   
   # Install dependencies
   RUN uv sync
   
   EXPOSE $PORT
   
   # Run the FastMCP server
   CMD ["uv", "run", "server.py"]
   

Deploy to Cloud Run

You can deploy the MCP server as a container image or as source code:

gcloud run deploy mcp-server --no-allow-unauthenticated --region=us-central1 --source .

Authenticate MCP client

If you deployed your service with the --no-allow-unauthenticated flag, any MCP client that connects to your remote MCP server must authenticate.

1. Grant the Cloud Run Invoker (roles/run.invoker) role to the service account. This Identity and Access Management policy binding makes sure that a strong security mechanism is used to authenticate your local MCP client.

2. Run the Cloud Run proxy to create an authenticated tunnel to the remote MCP server on your local machine:

   gcloud run services proxy mcp-server --region=us-central1
   

   If the Cloud Run proxy is not yet installed, this command prompts you to download the proxy. Follow the prompts to download and install the proxy.

Cloud Run authenticates all traffic to http://127.0.0.1:8080 and forwards requests to the remote MCP server.

Test the remote MCP server

You test and connect to the remote MCP server by using the FastMCP client and accessing the URL http://127.0.0.1:8080/mcp.

To test and invoke the add and subtract mechanism, follow these steps:

1. Before running the test server, run the Cloud Run proxy.

2. Create a test file called test_server.py and add the following code:

   import asyncio
   
   from fastmcp import Client
   
   async def test_server():
       # Test the MCP server using streamable-http transport.
       # Use "/sse" endpoint if using sse transport.
       async with Client("http://localhost:8080/mcp") as client:
           # List available tools
           tools = await client.list_tools()
           for tool in tools:
               print(f">>> 🛠️  Tool found: {tool.name}")
           # Call add tool
           print(">>> 🪛  Calling add tool for 1 + 2")
           result = await client.call_tool("add", {"a": 1, "b": 2})
           print(f"<<< ✅ Result: {result[0].text}")
           # Call subtract tool
           print(">>> 🪛  Calling subtract tool for 10 - 3")
           result = await client.call_tool("subtract", {"a": 10, "b": 3})
           print(f"<<< ✅ Result: {result[0].text}")
   
   if __name__ == "__main__":
       asyncio.run(test_server())

3. In a new terminal, run the test server:

   uv run test_server.py
   

   You should see the following output:

    🛠️ Tool found: add
    🛠️ Tool found: subtract
    🪛 Calling add tool for 1 + 2
    ✅ Result: 3
    🪛 Calling subtract tool for 10 - 3
    ✅ Result: 7
   

What's next

• Learn more about deploying AI applications on Cloud Run.

• Learn more about hosting MCP servers on Cloud Run.

• Learn how to use an MCP server to deploy code to Cloud Run.