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 maneira como os agentes de IA interagem com o ambiente. O agente de IA hospeda um cliente do MCP, e as ferramentas e recursos com que ele interage são servidores do 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 remotos do MCP 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 do MCP com transporte HTTP transmissível, mas não de servidores do 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 do MCP, especificando a ferramenta a ser executada. Depois que o servidor do MCP executa a ação e recupera os resultados, ele retorna o resultado ao cliente do MCP em um formato consistente.

Um servidor MCP interage com um agente de IA por meio de um cliente MCP.
Figura 1: o servidor do 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 do MCP ou usando um servidor do 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. Clientes novos também recebem US $300 em créditos 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 o ambiente de desenvolvimento do Cloud Run no seu Google Cloud projeto do.
  7. Verifique se você tem as permissões adequadas para implantar serviços e os papéis 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 do IAM necessários à 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.

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

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

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

Imagens do Container

Os servidores remotos do MCP distribuídos como imagens de 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 do MCP empacotado como uma imagem de contêiner, é necessário ter o URL da imagem de 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 do 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 das fontes, principalmente se forem escritos em Node.js ou Python.

  1. Clone o repositório Git do servidor do 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 HTTP do MCP no Cloud Run, o servidor do 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 do 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 do 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 remoto do MCP 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 remoto do MCP 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 corresponde 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 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 do MCP como um arquivo secundário

O servidor do 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 do 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 e o cliente do 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 remoto do MCP 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 do MCP para ter um nome abreviado no mesh, e o cliente do MCP pode se comunicar com o servidor do MCP usando o nome abreviado http://mcp-server. A autenticação é gerenciada pelo mesh.

A seguir