Hospedar servidores MCP no Cloud Run

Este guia mostra como hospedar um servidor do protocolo de contexto de modelo (MCP) com transporte HTTP transmitível no Cloud Run e fornece orientações para autenticar clientes do MCP. Se você não conhece o MCP, leia o guia de introdução para mais contexto.

O MCP é um protocolo aberto que padroniza como os agentes de IA interagem com o ambiente. O agente de IA hospeda um cliente MCP, e as ferramentas e os recursos com que ele interage são servidores MCP. O cliente MCP pode se comunicar com o servidor MCP por dois tipos de transporte distintos:

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

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

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

Antes de começar

  1. 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.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    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.

    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 projeto do Google Cloud .
  7. 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.

    8. Saiba como conceder os papéis

    Console

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

      Acessar o 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 da Conta do Google 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 pelo número do projeto Google Cloud .
    • PROJECT_ID com o Google Cloud ID do projeto.
    • PRINCIPAL com a conta a que você está adicionando a vinculação. Normalmente, é o endereço de e-mail da Conta do Google usado para implantar o serviço do Cloud Run.
    • ROLE com o papel que você está adicionando à conta do implantador.

    Hospedar servidores MCP HTTP remotos ou transmitíveis

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

    Para implantar esse tipo de servidor MCP no Cloud Run, é possível implantar o servidor MCP como uma imagem de 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 de contêiner são servidores da Web que recebem solicitações HTTP em uma porta específica. Isso significa que eles obedecem 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 de contêiner, você precisa 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 do contêiner, por exemplo us-docker.pkg.dev/cloudrun/container/mcp.
    • PORT com a porta em que ele detecta, por exemplo, 3000.

    Fontes

    Servidores MCP remotos 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 MCP: 

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

    2. Navegue até a raiz do servidor 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 MCP no Cloud Run, ele recebe um URL HTTPS, e a comunicação pode usar o suporte integrado do Cloud Run para streaming de respostas HTTP.

    Autenticar clientes MCP

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

    Autenticar clientes MCP locais

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

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

    Permissão do IAM do chamador

    Por padrão, o URL dos serviços do Cloud Run exige que todas as solicitações sejam autorizadas com o papel do IAM 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 seu cliente MCP local.

    Depois de implantar o servidor MCP em um serviço do Cloud Run em uma região, execute o proxy do Cloud Run na sua 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 serviço do Cloud Run.
    • REGION com a Google Cloud região em que você implantou o serviço. Por exemplo, europe-west1.

    O comando do 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 seu cliente com o seguinte:

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

    Se o cliente MCP não for compatível com o atributo url, use o pacote npm mcp-remote:

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

    Token de ID do OIDC

    Dependendo de o cliente MCP expor cabeçalhos ou usar uma maneira de fornecer um transporte autenticado personalizado, considere autenticar o cliente 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 Google Auth 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 do cliente, como Authorization: Bearer <token value>.

    Se o cliente de MCP não expuser cabeçalhos nem transporte, use outro método de autenticação.

    Autenticar clientes MCP em execução no Cloud Run

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

    Implantar o servidor MCP como um arquivo secundário

    O servidor MCP pode ser implantado como um sidecar em que o cliente 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 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 a serviço

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

    Usar o Cloud Service Mesh

    Um agente que hospeda um cliente MCP pode se conectar a um servidor MCP remoto usando o Cloud Service Mesh.

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

    A seguir