Esta página foi traduzida pela API Cloud Translation.

Crie e implemente um servidor MCP remoto no Cloud Run

Este tutorial mostra-lhe como criar e implementar um servidor do Protocolo de contexto do modelo (MCP) remoto no Cloud Run através do transporte HTTP streamable. Com o transporte HTTP por stream, o servidor MCP funciona como um processo independente que pode processar várias ligações de clientes.

Objetivos

Neste tutorial, vai:

Prepare o seu projeto Python com o gestor de pacotes uv.
Crie um servidor MCP para operações matemáticas.
Implementar no Cloud Run.
Autentique o cliente do MCP.
Teste o servidor MCP remoto.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Run Admin API, and Cloud Build APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

Configure o ambiente de programação do Cloud Run no seu Google Cloud projeto.
Certifique-se de que tem as autorizações adequadas para implementar serviços e as funções Administrador do Cloud Run (roles/run.admin) e Utilizador da conta de serviço (roles/iam.serviceAccountUser) concedidas à sua conta.
Conceda a função Cloud Run Invoker (roles/run.invoker) à sua conta. Esta função permite que o servidor MCP remoto aceda ao serviço do Cloud Run.

Saiba como conceder as funções

Consola

Na Google Cloud consola, aceda à página IAM.
Aceda ao IAM
Selecione o projeto.
Clique em Conceder acesso.
No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email da Conta Google usado para implementar o serviço do Cloud Run.
Na lista Selecionar uma função, selecione uma função.
Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
Clique em Guardar.

gcloud

Para conceder as funções de IAM necessárias à sua conta no seu projeto:

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

Substituição:

PROJECT_NUMBER: o número do seu Google Cloud projeto.
PROJECT_ID: o ID do seu Google Cloud projeto.
PRINCIPAL: o endereço de email da conta à qual está a conceder a função.
ROLE: a função que está a adicionar à conta do implementador.

Se estiver ao abrigo de uma política da organização de restrição de domínio que restringe invocações não autenticadas para o seu projeto, tem de aceder ao serviço implementado conforme descrito em Testar serviços privados.
Instale o Uv, um gestor de projetos e pacotes Python.

Prepare o seu projeto Python

Os passos seguintes descrevem como configurar o seu projeto Python com o gestor de pacotes uv.

Crie uma pasta denominada mcp-on-cloudrun para armazenar o código-fonte para a implementação:
```
  mkdir mcp-on-cloudrun
  cd mcp-on-cloudrun
```

Crie um projeto Python com a ferramenta uv para gerar um ficheiro 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 ficheiro 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 = []

Crie os seguintes novos ficheiros adicionais:
- server.py para o código-fonte do servidor MCP
- test_server.py para testar o servidor remoto
- Um ficheiro Docker para implementação no Cloud Run
```
touch server.py test_server.py Dockerfile
```
O diretório do projeto deve conter a seguinte estrutura:
```
├── mcp-on-cloudrun
│   ├── pyproject.toml
│   ├── server.py
│   ├── test_server.py
│   └── Dockerfile
```

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

Para fornecer um contexto valioso para melhorar a utilização de MDIs com o MCP, configure um servidor do MCP matemático com o FastMCP. O FastMCP oferece uma forma rápida de criar servidores e clientes MCP com Python.

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

Execute o seguinte comando para adicionar o FastMCP como uma dependência no ficheiro pyproject.toml:
```
uv add fastmcp==2.8.0 --no-sync
```

Adicione o seguinte código-fonte do servidor MCP matemático no ficheiro 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),
        )
    )

Inclua o seguinte código no Dockerfile para usar a ferramenta uv para executar o ficheiro server.py:

# 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"]

Implemente no Cloud Run

Pode implementar o servidor MCP como uma imagem de contentor ou como código-fonte:

Imagem de contentor

Para implementar um servidor MCP incluído num pacote como uma imagem de contentor, siga estas instruções.

Crie um repositório do Artifact Registry para armazenar a imagem de contentor:

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

Crie a imagem de contentor 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

Implemente a imagem do contentor do servidor da MCP no 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

Origem

Pode implementar servidores MCP remotos no Cloud Run a partir das respetivas origens.

Implemente a partir da origem executando o seguinte comando:

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

Autentique o cliente do MCP

Se implementou o seu serviço com a flag --no-allow-unauthenticated, qualquer cliente MCP que se ligue ao seu servidor MCP remoto tem de ser autenticado.

Conceda a função Cloud Run Invoker (roles/run.invoker) à conta de serviço. Esta associação de políticas de gestão de identidades e acessos garante que é usado um mecanismo de segurança forte para autenticar o seu cliente MCP local.
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, este comando pede-lhe que transfira o proxy. Siga as instruções para transferir e instalar o proxy.

O Cloud Run autentica todo o tráfego para http://127.0.0.1:8080 e encaminha pedidos para o servidor MCP remoto.

Teste o servidor MCP remoto

Teste e estabeleça ligação ao servidor MCP remoto através do cliente FastMCP e acedendo ao URL http://127.0.0.1:8080/mcp.

Para testar e invocar o mecanismo de adição e subtração, siga estes passos:

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

Crie um ficheiro de teste denominado 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[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())

Num novo terminal, execute o servidor de teste:

uv run test_server.py

Deverá ver o seguinte resultado:

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

Limpar

Para evitar custos adicionais na sua conta do Google Cloud , elimine todos os recursos que implementou com este tutorial.

Elimine o projeto

Se criou um novo projeto para este tutorial, elimine-o. Se usou um projeto existente e precisa de o manter sem as alterações que adicionou neste tutorial, elimine os recursos que criou para o tutorial.

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

Elimine recursos de tutoriais

Elimine o serviço do Cloud Run que implementou neste tutorial. Os serviços do Cloud Run não incorrem em custos até receberem pedidos.

Para eliminar o seu serviço do Cloud Run, execute o seguinte comando:
```
gcloud run services delete SERVICE-NAME
```
Substitua SERVICE-NAME pelo nome do seu serviço.

Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.
Remova a configuração da região predefinida gcloud que adicionou durante a configuração do tutorial:
```
 gcloud config unset run/region
```
Remova a configuração do projeto:
```
 gcloud config unset project
```

Crie e implemente um servidor MCP remoto no Cloud Run Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Objetivos

Custos

Antes de começar

Saiba como conceder as funções

Consola

gcloud

Prepare o seu projeto Python

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

Implemente no Cloud Run

Imagem de contentor

Origem

Autentique o cliente do MCP

Teste o servidor MCP remoto

Limpar

Elimine o projeto

Elimine recursos de tutoriais

Crie e implemente um servidor MCP remoto no Cloud Run