Aloje servidores MCP no Cloud Run

Este guia mostra como alojar um servidor do protocolo Model Context Protocol (MCP) com transporte HTTP de streaming no Cloud Run e fornece orientações para autenticar clientes do MCP. Se for a primeira vez que usa o MCP, leia o guia de introdução para ter mais contexto.

O MCP é um protocolo aberto que padroniza a forma como os agentes de IA interagem com o respetivo ambiente. O agente de IA aloja um cliente MCP, e as ferramentas e os recursos com os quais interage são servidores MCP. O cliente do MCP pode comunicar com o servidor do MCP através de dois tipos de transporte distintos:

Pode alojar clientes e servidores MCP na mesma máquina local, alojar um cliente MCP localmente e fazê-lo comunicar com servidores MCP remotos alojados numa plataforma na nuvem, como o Cloud Run, ou alojar o cliente e o servidor MCP numa plataforma na nuvem.

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

As orientações nesta página aplicam-se se estiver a desenvolver o seu próprio servidor MCP ou se estiver a usar 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 programação do Cloud Run no seu Google Cloud projeto.
  7. Certifique-se de que tem as autorizações adequadas para implementar serviços e que as funções administrador do Cloud Run (roles/run.admin) e utilizador da conta de serviço (roles/iam.serviceAccountUser) foram concedidas à sua conta.

    8. Saiba como conceder as funções

    Consola

    1. Na Google Cloud consola, aceda à página IAM.

      Aceda ao IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.

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

    5. Na lista Selecionar uma função, selecione uma função.
    6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
    7. 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

    Substituir:

    • PROJECT_NUMBER com o número do seu Google Cloud projeto.
    • PROJECT_ID com o seu Google Cloud ID do projeto.
    • PRINCIPAL com a conta à qual está a adicionar a associação. Normalmente, trata-se do endereço de email da Conta Google que é usado para implementar o serviço do Cloud Run.
    • ROLE com a função que está a adicionar à conta do implementador.

    Alojamento de servidores SSE remotos ou HTTP MCP de streaming

    Os servidores MCP que usam os eventos enviados pelo servidor (SSE) ou o transporte HTTP streamable podem ser alojados remotamente dos respetivos clientes MCP.

    Para implementar este tipo de servidor MCP no Cloud Run, pode implementar o servidor MCP como uma imagem de contentor ou como código fonte (normalmente Node.js ou Python), consoante a forma como o servidor MCP é embalado.

    Imagens de contentores

    Os servidores MCP remotos distribuídos como imagens de contentores são servidores Web que ouvem pedidos HTTP numa porta específica, o que significa que cumprem o contrato de tempo de execução do contentor do Cloud Run e podem ser implementados num serviço do Cloud Run.

    Para implementar um servidor MCP incluído num pacote como uma imagem de contentor, tem de ter o URL da imagem de contentor e a porta na qual espera receber pedidos. Estas podem ser implementadas através do seguinte comando da CLI gcloud:

    gcloud run deploy --image IMAGE_URL --port PORT

    Substituir:

    • IMAGE_URL com o URL da imagem do contentor, por exemplo, us-docker.pkg.dev/cloudrun/container/mcp.
    • PORT com a porta que escuta, por exemplo, 3000.

    Fontes

    Os servidores MCP remotos que não são fornecidos como imagens de contentores podem ser implementados no Cloud Run a partir das respetivas origens, especialmente 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 para a raiz do servidor MCP: 

      cd REPOSITORY

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

      gcloud run deploy --source .

    Depois de implementar o seu 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.

    Autentique clientes do MCP

    Consoante onde alojou o cliente do MCP, consulte a secção relevante para si:

    Autentique clientes MCP locais

    Se o agente de IA que aloja o cliente do MCP for executado numa 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 a autenticação.

    Autorização de invocador do IAM

    Por predefinição, o URL dos serviços do Cloud Run requer que todos os pedidos sejam autorizados com a função do IAM Cloud Run Invoker (roles/run.invoker). Esta associação da política de IAM garante que é usado um mecanismo de segurança forte para autenticar o seu cliente MCP local.

    Depois de implementar o servidor MCP num serviço do Cloud Run numa região, execute o proxy do Cloud Run na sua máquina local para expor em segurança o servidor MCP remoto ao seu cliente através das suas próprias credenciais:

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

    Substituir:

    • MCP_SERVER_NAME com o nome do seu serviço do Cloud Run.
    • REGION com a Google Cloud região onde implementou o seu serviço. Por exemplo, europe-west1.

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

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

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

    Se o seu cliente do MCP não suportar 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

    Consoante o cliente do MCP exponha cabeçalhos ou use uma forma de fornecer um transporte autenticado personalizado, pode considerar autenticar o cliente do MCP com um token de ID do OIDC.

    Pode usar várias bibliotecas de autenticação Google para obter um token de ID do ambiente de tempo de execução, por exemplo, a biblioteca Google Auth para Python. Este token tem de ter a reivindicação de público-alvo correta que corresponda ao URL *.run.app do serviço de receção, a menos que use públicos-alvo personalizados. Também tem de incluir o token de ID em pedidos de cliente, como Authorization: Bearer <token value>.

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

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

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

    Implemente o servidor MCP como um sidecar

    O servidor MCP pode ser implementado como um sidecar onde o cliente MCP é executado.

    Não é necessária nenhuma autenticação específica para este exemplo de utilização, uma vez que o cliente do MCP e o servidor do MCP estão na mesma instância. O cliente pode estabelecer ligação ao servidor MCP através de uma porta em http://localhost:PORT. Substitua PORT por uma porta diferente da usada para enviar pedidos ao serviço Cloud Run.

    Autentique serviço a serviço

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

    Use o Cloud Service Mesh

    Um agente que aloja um cliente MCP pode estabelecer ligação a um servidor MCP remoto através da Cloud Service Mesh.

    Pode configurar o serviço do servidor MCP para ter um nome curto na malha e o cliente MCP pode comunicar com o servidor MCP através do nome curtohttp://mcp-server. A autenticação é gerida pela malha.

    O que se segue?