Hospedar servidores MCP no Cloud Run

Este guia mostra como hospedar um servidor do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) com transporte HTTP transmissível no Cloud Run e fornece orientações para autenticar clientes do MCP. Se você não conhece o MCP, leia os seguintes recursos:

O MCP é um protocolo aberto que padroniza a interação dos agentes de IA com o ambiente. O agente de IA hospeda um cliente do MCP, e as ferramentas e recursos com que ele interage são servidores MCP. O cliente do MCP pode se comunicar com o servidor do MCP em dois tipos de transporte distintos:

É possível hospedar clientes e servidores do MCP na mesma máquina local, hospedar um cliente do MCP localmente e fazer com que ele se comunique com servidores do MCP remotos hospedados em uma plataforma de nuvem como o Cloud Run ou hospedar o cliente e o servidor do MCP em uma plataforma de nuvem.

O Cloud Run oferece suporte à hospedagem de servidores MCP com transporte HTTP transmissível, mas não de servidores MCP com transporte stdio.

O diagrama a seguir mostra como o cliente do MCP recebe a intenção do agente de IA e envia uma solicitação padronizada aos servidores MCP, especificando a ferramenta a ser executada. Depois que o servidor MCP executa a ação e recupera os resultados, o servidor MCP retorna o resultado ao cliente MCP em um formato consistente.

Um servidor MCP interage com um agente de IA por um cliente MCP.
Figura 1: o servidor MCP hospedado no Cloud Run interage com o cliente do MCP, que interage com o agente de IA.

As orientações nesta página se aplicam se você estiver desenvolvendo seu próprio servidor MCP ou usando um servidor MCP atual.

Antes de começar

  1. Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Novos clientes também recebem US$ 300 em créditos sem custo financeiro para executar, testar e implantar cargas de trabalho.

  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 the resourcemanager.projects.create permission. Learn how to grant roles.

    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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  6. Configure seu ambiente de desenvolvimento do Cloud Run no seu Google Cloud projeto.
  7. Verifique se você tem as permissões adequadas para implantar serviços e os papéis de administrador do Cloud Run (roles/run.admin) e usuário da conta de serviço (roles/iam.serviceAccountUser) concedidos à sua conta.

    8. Saiba como conceder os papéis

    Console

    1. No Google Cloud console, 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 extra.
    7. Clique em Salvar.

    gcloud

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

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

    Substitua:

    • PROJECT_NUMBER pelo número do seu Google Cloud projeto número.
    • PROJECT_ID pelo ID do seu Google Cloud projeto.
    • PRINCIPAL com a conta para a qual você está adicionando a vinculação. Normalmente, esse é o endereço de e-mail que é usado para implantar o serviço do Cloud Run.
    • ROLE pelo papel que você está adicionando à conta do implantador.
  8. Consulte os preços do Cloud Run ou estime os custos com a calculadora de preços.

Hospedar servidores remotos do MCP de SSE ou HTTP transmissível

Os servidores MCP que usam os eventos enviados pelo servidor (SSE) ou o transporte HTTP transmissível podem ser hospedados remotamente dos clientes MCP.

Para implantar esse tipo de servidor MCP no Cloud Run, você pode implantar o servidor MCP como uma imagem do contêiner ou como código-fonte (geralmente Node.js ou Python), dependendo de como o servidor MCP é empacotado.

Imagens do Container

Os servidores MCP remotos distribuídos como imagens do contêiner são servidores da Web que ficam à espera de solicitações HTTP em uma porta específica, o que significa que eles aderem ao contrato de ambiente de execução de contêiner do Cloud Run e podem ser implantados em um serviço do Cloud Run.

Para implantar um servidor MCP empacotado como uma imagem do contêiner, é necessário ter o URL da imagem do contêiner e a porta em que ele espera receber solicitações. Eles podem ser implantados usando o seguinte comando da CLI gcloud:

gcloud run deploy --image IMAGE_URL --port PORT

Substitua:

  • IMAGE_URL pelo URL da imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/mcp.
  • PORT pela porta em que ele fica à espera, por exemplo, 3000.

Fontes

Os servidores remotos do MCP que não são fornecidos como imagens de contêiner podem ser implantados no Cloud Run pelas fontes, principalmente se forem escritos em Node.js ou Python.

  1. Clone o repositório Git do servidor MCP: 

    git clone https://github.com/ORGANIZATION/REPOSITORY.git

  2. Navegue até a raiz do servidor do MCP: 

    cd REPOSITORY

  3. Implante no Cloud Run com o seguinte comando da CLI gcloud: 

    gcloud run deploy --source .

Depois de implantar o servidor MCP HTTP no Cloud Run, o servidor MCP recebe um URL HTTPS e a comunicação pode usar o suporte integrado do Cloud Run para streaming de respostas HTTP.

Autenticar clientes do MCP para agentes de IA

Dependendo de onde você hospedou o cliente do MCP, consulte a seção relevante para você:

Autenticar clientes locais do MCP

Se o agente de IA que hospeda o cliente do MCP for executado em uma máquina local, use um dos seguintes métodos para autenticar o cliente do MCP:

Para mais informações, consulte a especificação do MCP sobre autenticação.

Permissão de invocador do IAM

Por padrão, o URL dos serviços do Cloud Run exige que todas as solicitações sejam autorizadas com o papel do IAM de invocador do Cloud Run (roles/run.invoker). Essa vinculação de política do IAM garante que um mecanismo de segurança forte seja usado para autenticar o cliente local do MCP.

Depois de implantar o servidor MCP em um serviço do Cloud Run em uma região, execute o proxy do Cloud Run na máquina local para expor com segurança o servidor MCP remoto ao cliente usando suas próprias credenciais:

gcloud run services proxy MCP_SERVER_NAME --region REGION --port=3000

Substitua:

  • MCP_SERVER_NAME pelo nome do seu serviço do Cloud Run.
  • REGION pela Google Cloud região em que você implantou o serviço. Por exemplo, europe-west1.

O comando de proxy do Cloud Run cria um proxy local na porta 3000 que encaminha solicitações para o servidor MCP remoto e injeta sua identidade.

Atualize o arquivo de configuração do MCP do cliente do MCP com o seguinte:

{
  "mcpServers": {
    "cloud-run": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Se o cliente do MCP não oferecer suporte ao url atributo, use o mcp-remote pacote npm:

{
  "mcpServers": {
    "cloud-run": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/sse"
      ]
    }
  }
}

Token de ID do OIDC

Dependendo se o cliente do MCP expõe cabeçalhos ou usa uma maneira de fornecer um transporte autenticado personalizado, você pode autenticar o cliente do MCP com um token de ID do OIDC.

É possível usar várias bibliotecas de autenticação do Google para receber um token de ID do ambiente de execução, por exemplo, a Biblioteca de autenticação do Google para Python. Esse token precisa ter a declaração de público-alvo correta que corresponda ao URL *.run.app do serviço de recebimento, a menos que você use públicos-alvo personalizados. Você também precisa incluir o token de ID em solicitações de cliente, como Authorization: Bearer <token value>.

Se o cliente do MCP não expuser cabeçalhos ou transporte, use um método de autenticação diferente.

Autenticar clientes locais do MCP com o IAP

Esta seção descreve como autenticar clientes locais do MCP que estão em execução no Cloud Run.

Para criar a política de entrada, faça o seguinte:

  1. Conceda o papel de invocador do Cloud Run (roles/run.invoker) ao agente de serviço do IAP.

    gcloud run services add-iam-policy-binding SERVICE_NAME \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com' \
    --role='roles/run.invoker'

    Substitua o seguinte:

    • SERVICE_NAME: o nome do serviço ao qual adicionar a vinculação de política

    • PROJECT_NUMBER: o número do projeto que contém o serviço

  2. Ative o IAP no serviço do Cloud Run.

    Criar

    Para ativar a autenticação do IAP para um novo serviço, execute o seguinte comando:

    gcloud run deploy SERVICE_NAME --image=MCP_SERVER_IMAGE
  --functional-type=MCP_SERVER \
  --region=REGION \
  --iap

    Substitua o seguinte:

    • SERVICE_NAME: o nome do serviço ao qual adicionar a vinculação de política

    • MCP_SERVER_IMAGE: o caminho da imagem do servidor MCP

    • REGION: a Google Cloud região em que você quer implantar o serviço, por exemplo, europe-west1

    Atualizar

    Para ativar a autenticação do IAP para um serviço atual, execute o seguinte comando:

    gcloud run services update SERVICE_NAME \
  --region=REGION \
  --functional-type=MCP_SERVER \
  --iap

    Substitua o seguinte:

    • SERVICE_NAME: o nome do serviço a ser atualizado

    • REGION: a Google Cloud região em que você implantou o serviço, por exemplo, europe-west1

Autenticar clientes do MCP em execução no Cloud Run

Se o agente de IA que hospeda o cliente do MCP for executado no Cloud Run, use um dos seguintes métodos para autenticar o cliente do MCP:

Implantar o servidor MCP como um arquivo secundário

O servidor MCP pode ser implantado como um arquivo secundário em que o cliente do MCP é executado.

Nenhuma autenticação específica é necessária para esse caso de uso, já que o cliente e o servidor MCP estão na mesma instância. O cliente pode se conectar ao servidor do MCP usando uma porta em http://localhost:PORT. Substitua PORT por uma porta diferente da usada para enviar solicitações ao serviço do Cloud Run.

Autenticar serviço para serviço

Se o servidor MCP e o cliente MCP forem executados como serviços distintos do Cloud Run, consulte Autenticação de serviço para serviço.

Usar o Cloud Service Mesh

Um agente que hospeda um cliente do MCP pode se conectar a um servidor MCP remoto usando o Cloud Service Mesh. O uso de uma malha de serviço simplifica a orquestração de microsserviços, processando a autenticação e o gerenciamento de tráfego automaticamente.

É possível configurar o serviço do servidor MCP para ter um nome abreviado no mesh, e o cliente do MCP pode se comunicar com o servidor MCP usando o nome abreviado http://mcp-server. A autenticação é gerenciada pelo mesh.

A seguir