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.

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:

Container image

To deploy an MCP server packaged as a container image, follow these instructions.

1. Create an Artifact Registry repository to store the container image:

   gcloud artifacts repositories create remote-mcp-servers \
   --repository-format=docker \
   --location=us-central1 \
   --description="Repository for remote MCP servers" \
   --project=PROJECT_ID
   

2. Build the container image and push it to Artifact Registry with Cloud Build:

   gcloud builds submit --region=us-central1 --tag us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest
   

3. Deploy the MCP server container image to Cloud Run:

   gcloud run deploy mcp-server \
   --image us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest \
   --region=us-central1 \
   --no-allow-unauthenticated
   

Source

You can deploy remote MCP servers to Cloud Run from their sources.

Deploy from source by running the following command:

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
   

Success: You successfully deployed a remote MCP server to Cloud Run and tested it using the FastMCP client.