Ospitare i server MCP su Cloud Run

Questa guida mostra come ospitare un server Model Context Protocol (MCP) con trasporto HTTP trasmissibile su Cloud Run e fornisce indicazioni per l'autenticazione dei client MCP. Se non hai mai utilizzato MCP, leggi la guida introduttiva per maggiori dettagli.

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 trasmissibile, ma non di server MCP con trasporto stdio.

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

Prima di iniziare

  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. Make sure 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. Make sure that billing is enabled for your Google Cloud project.

  6. Configura l'ambiente di sviluppo Cloud Run nel tuo progetto Google Cloud .
  7. Assicurati di disporre delle autorizzazioni appropriate per il deployment dei servizi e dei ruoli Amministratore di Cloud Run (roles/run.admin) e Utente service account (roles/iam.serviceAccountUser) concessi al tuo account.

    8. Scopri come concedere i ruoli

    Console

    1. Nella console Google Cloud 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 utente. In genere, si tratta dell'indirizzo email dell'Account Google utilizzato per il deployment del servizio Cloud Run.

    5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
    6. Per concedere altri ruoli, 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 progetto Google Cloud .
    • PROJECT_ID con l'ID progetto Google Cloud .
    • PRINCIPAL con l'account per cui stai aggiungendo il collegamento. In genere, si tratta dell'indirizzo email dell'Account Google utilizzato per il deployment del servizio Cloud Run.
    • ROLE con il ruolo che stai aggiungendo all'account deployer.

    Ospita server MCP HTTP remoti SSE o riproducibili in streaming

    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 rimangono in ascolto delle richieste HTTP su una porta specifica, il che significa che rispettano il contratto di runtime del 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 implementati 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 deployati su Cloud Run dalle loro 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 in 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

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

    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 ulteriori informazioni, 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 Invoker di Cloud Run (roles/run.invoker). Questo binding dei criteri IAM garantisce che venga utilizzato 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 tua macchina locale per esporre in modo sicuro il server MCP remoto al tuo 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 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 i seguenti valori:

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

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

    {
  "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 corrisponde all'URL *.run.app del servizio ricevente, 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:

    Esegui il deployment del server MCP come sidecar

    Il server MCP può essere implementato come sidecar in cui viene eseguito il client MCP.

    Per questo caso d'uso non è richiesta alcuna autenticazione specifica, poiché il client MCP 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 richieste al servizio Cloud Run.

    Autenticare il servizio

    Se il server MCP 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.

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

    Passaggi successivi