Ospitare i server MCP su Cloud Run

Questa guida mostra come ospitare un server Model Context Protocol (MCP) con trasporto HTTP streamable su Cloud Run e fornisce indicazioni per l'autenticazione dei client MCP. Se non hai familiarità con MCP, consulta le seguenti risorse:

MCP è un protocollo aperto che standardizza il modo in cui gli agenti AI interagiscono con il loro ambiente. L'agente AI ospita un client MCP e gli strumenti e le risorse con cui interagisce sono server MCP. Il client MCP può comunicare con il server MCP tramite due tipi di trasporto distinti:

Puoi ospitare client e server MCP sulla stessa macchina locale, ospitare un client MCP localmente e farlo comunicare con server MCP remoti ospitati su una piattaforma cloud come Cloud Run oppure ospitare sia il client che il server MCP su una piattaforma cloud.

Cloud Run supporta l'hosting di server MCP con trasporto HTTP streamable, ma non di server MCP con trasporto stdio.

Il seguente diagramma mostra come il client MCP prende l'intento dell'agente AI e invia una richiesta standardizzata ai server MCP, specificando lo strumento da eseguire. Dopo che il server MCP esegue l'azione e recupera i risultati, li restituisce al client MCP in un formato coerente.

Un server MCP interagisce con un agente AI tramite un client MCP.
Figura 1.Il server MCP ospitato su Cloud Run interagisce con il client MCP, che a sua volta interagisce con l'agente AI.

Le indicazioni riportate in questa pagina si applicano se stai sviluppando il tuo server MCP o se ne stai utilizzando uno esistente.

Prima di iniziare

  1. Accedi al tuo Google Cloud account. Se non hai familiarità con Google Cloud, crea un account per valutare il rendimento dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per eseguire, testare ed eseguire il deployment dei carichi di lavoro.

  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. Configura l'ambiente di sviluppo Cloud Run nel tuo Google Cloud progetto.
  7. Assicurati di disporre delle autorizzazioni appropriate per eseguire il deployment dei servizi e che al tuo account siano stati concessi i ruoli Amministratore Cloud Run (roles/run.admin) e Utente account di servizio (roles/iam.serviceAccountUser).

    8. Scopri come concedere i ruoli

    Console

    1. Nella Google Cloud console vai alla pagina IAM.

      Vai a IAM
    2. Seleziona il progetto.
    3. Fai clic su Concedi l'accesso.

    4. Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email utilizzato per eseguire il deployment del servizio Cloud Run.

    5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
    6. Per concedere ruoli aggiuntivi, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.
    7. Fai clic su Salva.

    gcloud

    Per concedere i ruoli IAM richiesti al tuo account nel tuo progetto:

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

    Sostituisci:

    • PROJECT_NUMBER con il numero del tuo Google Cloud progetto
    • PROJECT_ID con l'ID del tuo Google Cloud progetto.
    • PRINCIPAL con l'account a cui stai aggiungendo l' associazione. In genere si tratta dell'indirizzo email che è utilizzato per eseguire il deployment del servizio Cloud Run.
    • ROLE con il ruolo che stai aggiungendo all'account del deployer.

Ospitare server MCP HTTP streamable o SSE remoti

I server MCP che utilizzano il trasporto HTTP streamable o Server-Sent Events (SSE) possono essere ospitati in remoto dai relativi client MCP.

Per eseguire il deployment di questo tipo di server MCP su Cloud Run, puoi eseguire il deployment del server MCP come immagine container o come codice sorgente (in genere Node.js o Python), a seconda di come è pacchettizzato il server MCP.

Immagini container

I server MCP remoti distribuiti come immagini container sono server web che ascoltano le richieste HTTP su una porta specifica, il che significa che rispettano il contratto di runtime dei container di Cloud Run e possono essere sottoposti a deployment in un servizio Cloud Run.

Per eseguire il deployment di un server MCP pacchettizzato come immagine container, devi disporre dell'URL dell'immagine container e della porta su cui prevede di ricevere le richieste. Questi possono essere sottoposti a deployment utilizzando il seguente comando gcloud CLI:

gcloud run deploy --image IMAGE_URL --port PORT

Sostituisci:

  • IMAGE_URL con l'URL dell'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/mcp.
  • PORT con la porta su cui è in ascolto, ad esempio 3000.

Fonti

I server MCP remoti non forniti come immagini container possono essere sottoposti a deployment su Cloud Run dalle relative origini, in particolare se sono scritti in Node.js o Python.

  1. Clona il repository Git del server MCP: 

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

  2. Vai alla radice del server MCP: 

    cd REPOSITORY

  3. Esegui il deployment su Cloud Run con il seguente comando gcloud CLI: 

    gcloud run deploy --source .

Dopo aver eseguito il deployment del server MCP HTTP su Cloud Run, il server MCP riceve un URL HTTPS e la comunicazione può utilizzare il supporto integrato di Cloud Run per lo streaming delle risposte HTTP.

Autenticare i client MCP per gli agenti AI

A seconda di dove hai ospitato il client MCP, consulta la sezione pertinente:

Autenticare i client MCP locali

Se l'agente AI che ospita il client MCP viene eseguito su una macchina locale, utilizza uno dei seguenti metodi per autenticare il client MCP:

Per saperne di più, consulta la specifica MCP sull'autenticazione.

Autorizzazione IAM invoker

Per impostazione predefinita, l'URL dei servizi Cloud Run richiede che tutte le richieste siano autorizzate con il ruolo IAM Cloud Run Invoker (roles/run.invoker). Questa associazione di policy IAM garantisce l'utilizzo di un meccanismo di sicurezza efficace per autenticare il client MCP locale.

Dopo aver eseguito il deployment del server MCP in un servizio Cloud Run in una regione, esegui il proxy Cloud Run sulla macchina locale per esporre in modo sicuro il server MCP remoto al client utilizzando le tue credenziali:

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

Sostituisci:

  • MCP_SERVER_NAME con il nome del tuo servizio Cloud Run.
  • REGION con la Google Cloud regione in cui hai eseguito il deployment del servizio. Ad esempio, europe-west1.

Il comando del proxy Cloud Run crea un proxy locale sulla porta 3000 che inoltra le richieste al server MCP remoto e inserisce la tua identità.

Aggiorna il file di configurazione MCP del client MCP con quanto segue:

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

Se il client MCP non supporta l'attributo url, utilizza il mcp-remote pacchetto npm:

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

Token ID OIDC

A seconda che il client MCP esponga le intestazioni o utilizzi un modo per fornire un trasporto autenticato personalizzato, potresti prendere in considerazione l'autenticazione del client MCP con un token ID OIDC.

Puoi utilizzare varie librerie di autenticazione Google per ottenere un token ID dall'ambiente di runtime, ad esempio la libreria di autenticazione Google per Python. Questo token deve avere l'attestazione del pubblico corretta che corrisponda all'URL *.run.app del servizio di ricezione, a meno che tu non utilizzi segmenti di pubblico personalizzati. Devi anche includere il token ID nelle richieste client, ad esempio Authorization: Bearer <token value>.

Se il client MCP non espone intestazioni o trasporto, utilizza un metodo di autenticazione diverso.

Autenticare i client MCP in esecuzione su Cloud Run

Se l'agente AI che ospita il client MCP viene eseguito su Cloud Run, utilizza uno dei seguenti metodi per autenticare il client MCP:

Eseguire il deployment del server MCP come sidecar

Il server MCP può essere sottoposto a deployment come sidecar in cui viene eseguito il client MCP.

Per questo caso d'uso non è richiesta alcuna autenticazione specifica, poiché il client e il server MCP si trovano sulla stessa istanza. Il client può connettersi al server MCP utilizzando una porta su http://localhost:PORT. Sostituisci PORT con una porta diversa da quella utilizzata per inviare le richieste al servizio Cloud Run.

Autenticare il servizio al servizio

Se il server e il client MCP vengono eseguiti come servizi Cloud Run distinti, consulta Autenticazione da servizio a servizio.

Utilizzare Cloud Service Mesh

Un agente che ospita un client MCP può connettersi a un server MCP remoto utilizzando Cloud Service Mesh. L'utilizzo di un mesh di servizi semplifica l'orchestrazione dei microservizi gestendo automaticamente l'autenticazione e la gestione del traffico.

Puoi configurare il servizio del server MCP in modo che abbia un nome breve sul mesh e il client MCP possa comunicare con il server MCP utilizzando il nome breve http://mcp-server. L'autenticazione è gestita dal mesh.

Passaggi successivi