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 de streaming no Cloud Run e fornece orientações para autenticar clientes MCP. Se você não conhece o MCP, leia os seguintes recursos:

• O que é o Protocolo de Contexto de Modelo (MCP)?

O MCP é um protocolo aberto que padroniza a interação dos agentes de IA 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:

• Eventos enviados pelo servidor (SSE) ou HTTP transmissível
• Entrada/saída padrão (stdio)

É 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 oferece suporte à hospedagem de servidores MCP com transporte HTTP por streaming, mas não a servidores MCP com transporte stdio.

O diagrama a seguir mostra como o cliente 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, ele os retorna ao cliente MCP em um formato consistente.

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

• Se você estiver desenvolvendo seu próprio servidor MCP, recomendamos usar um SDK de servidor MCP, como os SDKs de linguagem oficial (TypeScript, Python, Go, Kotlin, Java, C#, Ruby ou Rust) ou FastMCP.
• Se você estiver usando um servidor MCP atual, encontre uma lista de servidores MCP oficiais e da comunidade no repositório do GitHub de servidores MCP. O Docker Hub também oferece uma lista selecionada de servidores MCP.

Antes de começar

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

2. Verify that billing is enabled for your Cloud de Confiance project.

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

Saiba como conceder os papéis

Console

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

   Acessar IAM
2. Selecione o projeto.
3. Clique em person_add 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 add 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 projeto:

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

Substitua:

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

Hospedar servidores MCP HTTP remotos de SSE ou de streaming

Os servidores MCP que usam eventos enviados pelo servidor (SSE) ou transporte HTTP transmissível podem ser hospedados remotamente em relação aos 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.

gcloud run deploy --image IMAGE_URL --port PORT

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

Autenticar clientes MCP para agentes de IA

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

• Autenticar clientes MCP locais
• Autenticar clientes MCP em execução no Cloud Run

Autenticar clientes MCP locais

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

• Permissão de invocador do IAM
• Token de ID do OIDC
• Usar o IAP

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 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 pela Cloud de Confiance by S3NS 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 seu cliente MCP 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 se o cliente do MCP expõe cabeçalhos ou usa uma maneira de fornecer um transporte autenticado personalizado, considere 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 do Google Auth para Python. Esse token precisa ter a declaração de público-alvo correta que corresponda ao URL *.s3nsrun.fr do serviço de recebimento, a menos que você use públicos-alvo personalizados. Você também precisa incluir o token de ID nas solicitações do cliente, como Authorization: Bearer <token value>.

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

Autenticar clientes MCP locais com o IAP

Nesta seção, descrevemos 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.s3ns-system.iam.gserviceaccount.com' \
       --role='roles/run.invoker'
   

   Substitua:

   • 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 em 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:

   • 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 Cloud de Confiance região em que você quer implantar o serviço, por exemplo, europe-west1

   Atualizar

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

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

   Substitua:

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

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

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 como um arquivo secundário
• Autenticar entre serviços

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 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 MCP e o cliente MCP forem executados como serviços distintos do Cloud Run, consulte Como autenticar serviço a serviço.

A seguir

• Hospedar agentes de IA no Cloud Run.
• Siga um tutorial para criar e implantar um servidor MCP remoto no Cloud Run.
• Siga estes codelabs do MCP:
  • Como implantar um servidor MCP seguro no Cloud Run.
  • Usar um servidor MCP no Cloud Run com um agente do ADK.