Criar e implantar um servidor MCP remoto no Cloud Run

Neste tutorial, mostramos como criar e implantar um servidor remoto do Protocolo de Contexto de Modelo (MCP) no Cloud Run usando o transporte HTTP transmissível. Com o transporte HTTP transmissível, o servidor MCP opera como um processo independente que pode processar várias conexões de clientes.

Objetivos

Com este tutorial, você vai:

1. Prepare seu projeto Python com o gerenciador de pacotes uv.
2. Crie um servidor MCP para operações matemáticas.
3. Implantar no Cloud Run.
4. Autentique o cliente do MCP.
5. Teste o servidor MCP remoto.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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 the resourcemanager.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

Verify that billing is enabled for your Google Cloud project.

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 the resourcemanager.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

Verify that billing is enabled for your Google Cloud project.

1. Ative as APIs Artifact Registry, API Cloud Run Admin e API Cloud Build, se alguma delas ainda não estiver ativada.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

2. Configure o ambiente de desenvolvimento do Cloud Run no seu projeto do Google Cloud .
3. Verifique se você tem as permissões adequadas para implantar serviços e se os papéis Administrador do Cloud Run (roles/run.admin) e Usuário da conta de serviço (roles/iam.serviceAccountUser) foram concedidos à sua conta.
4. Conceda o papel Invocador do Cloud Run (roles/run.invoker) à sua conta. Essa função permite que o servidor MCP remoto acesse o serviço do Cloud Run.

Saiba como conceder os papéis

Console

1. No console do Google Cloud , acesse a página IAM.

   Acessar IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos principais, digite seu identificador de usuário. Normalmente, esse é o endereço de e-mail usado para implantar o serviço do Cloud Run.

5. Na lista Selecionar papel, escolha um.
6. Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.
7. Clique em Salvar.

gcloud

Para conceder os papéis do IAM necessários à sua conta no projeto:

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

Substitua:

• PROJECT_NUMBER: o número do projeto do Google Cloud .
• PROJECT_ID: o ID do projeto Google Cloud .
• PRINCIPAL: o endereço de e-mail da conta a que você está concedendo o papel.
• ROLE: o papel que você está adicionando à conta do implantador.

5. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

6. Instale o Uv, um gerenciador de projetos e pacotes Python.

Preparar seu projeto Python

As etapas a seguir descrevem como configurar seu projeto Python com o uv gerenciador de pacotes.

1. Crie uma pasta chamada mcp-on-cloudrun para armazenar o código-fonte da implantação:

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

2. Crie um projeto Python com a ferramenta uv para gerar um arquivo pyproject.toml:

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

   O comando uv init cria o seguinte arquivo pyproject.toml:

   [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. Crie estes novos arquivos adicionais:

   • server.py para o código-fonte do servidor MCP
   • test_server.py para testar o servidor remoto
   • Um Dockerfile para implantação no Cloud Run

   touch server.py test_server.py Dockerfile
   

   O diretório do projeto precisa ter a seguinte estrutura:

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

Criar um servidor MCP para operações matemáticas

Para fornecer um contexto valioso para melhorar o uso de LLMs com o MCP, configure um servidor MCP de matemática com o FastMCP. O FastMCP oferece uma maneira rápida de criar servidores e clientes MCP com Python.

Siga estas etapas para criar um servidor MCP para operações matemáticas, como adição e subtração.

1. Execute o comando a seguir para adicionar o FastMCP como uma dependência no arquivo pyproject.toml:

   uv add fastmcp==2.13.1 --no-sync
   

2. Adicione o seguinte código-fonte do servidor MCP de matemática ao arquivo server.py:

   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. Inclua o código a seguir no Dockerfile para usar a ferramenta uv e executar o arquivo server.py:

   # Use the official Python image
   FROM python:3.14-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"]
   

Implantar no Cloud Run

Você pode implantar o servidor MCP como uma imagem do contêiner ou como código-fonte:

Observação:somente os serviços do Cloud Run podem ser expostos como servidores MCP. Os jobs do Cloud Run não podem funcionar como servidores MCP.

Imagem do contêiner

Para implantar um servidor MCP empacotado como uma imagem de contêiner, siga estas instruções.

1. Crie um repositório do Artifact Registry para armazenar a imagem do contêiner:

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

2. Crie a imagem do contêiner e envie-a para o Artifact Registry com o Cloud Build:

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

3. Implante a imagem do contêiner do servidor MCP no Cloud Run:

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

Origem

É possível implantar servidores MCP remotos no Cloud Run usando as fontes deles.

Implante da origem executando o seguinte comando:

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

Verificar o registro no Agent Registry

Quando você implanta um serviço com --functional-type=mcp-server, ele é registrado automaticamente no Agent Registry como uma ferramenta.

Para verificar seu registro, acesse a guia Servidores MCP no console do Google Cloud.

Autenticar o cliente MCP

Se você implantou o serviço com a flag --no-allow-unauthenticated, qualquer cliente MCP que se conectar ao servidor MCP remoto precisará ser autenticado.

1. Conceda o papel Invocador do Cloud Run (roles/run.invoker) à identidade do seu agente. Para instruções, consulte Autenticar em servidores MCP no Cloud Run.
2. Use o Identity-Aware Proxy para proteger seus servidores MCP e ativar o OAuth. Para instruções, consulte Autenticar servidores MCP.

3. Execute o proxy do Cloud Run para criar um túnel autenticado para o servidor MCP remoto na sua máquina local:

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

   Se o proxy do Cloud Run ainda não estiver instalado, esse comando vai pedir que você faça o download dele. Siga as instruções para fazer o download e instalar o proxy.

O Cloud Run autentica todo o tráfego para http://127.0.0.1:8080 e encaminha solicitações ao servidor MCP remoto.

Testar o servidor MCP remoto

Teste e conecte-se ao servidor MCP remoto usando o cliente FastMCP e acessando o URL http://127.0.0.1:8080/mcp.

Para testar e invocar o mecanismo de adição e subtração, siga estas etapas:

1. Antes de executar o servidor de teste, execute o proxy do Cloud Run.

2. Crie um arquivo de teste chamado test_server.py e adicione o seguinte código:

   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.content[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.content[0].text}")
   
   
   if __name__ == "__main__":
       asyncio.run(test_server())

3. Em um novo terminal, execute o servidor de teste:

   uv run test_server.py
   

   Você verá esta resposta:

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

Sucesso: você implantou um servidor MCP remoto no Cloud Run e o testou usando o cliente FastMCP.

Limpar

Para evitar cobranças extras na sua conta do Google Cloud , exclua todos os recursos implantados com este tutorial.

Excluir o projeto

Se você criou um novo projeto para este tutorial, exclua-o. Se você usou um projeto atual e precisa mantê-lo sem as mudanças adicionadas neste tutorial, exclua os recursos criados para o tutorial.

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No console Google Cloud , acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Excluir recursos do tutorial

1. Exclua o serviço do Cloud Run que você implantou neste tutorial. Os serviços do Cloud Run não geram custos até receberem solicitações.

   Para excluir o serviço do Cloud Run, execute o seguinte comando:

   gcloud run services delete SERVICE-NAME

   SERVICE-NAME pelo nome do serviço;

   Também é possível excluir os serviços do Cloud Run no Google Cloud console do.

2. Remova a configuração de região padrão gcloud que você adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project
   

A seguir

• Saiba mais sobre como implantar aplicativos de IA no Cloud Run.

• Saiba mais sobre hospedar servidores MCP no Cloud Run.

• Saiba como usar um servidor MCP para implantar código no Cloud Run.