Crea ed esegui il deployment di un server MCP remoto su Cloud Run

Questo tutorial mostra come creare ed eseguire il deployment di un server Model Context Protocol (MCP) remoto su Cloud Run utilizzando il trasporto HTTP trasmissibile in streaming. Con il trasporto HTTP in streaming, il server MCP funziona come un processo indipendente in grado di gestire più connessioni client.

Obiettivi

In questo tutorial, imparerai a:

Prepara il tuo progetto Python con il gestore di pacchetti uv.
Crea un server MCP per le operazioni matematiche.
Esegui il deployment in Cloud Run.
Autentica il client MCP.
Testa il server MCP remoto.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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

Verify that billing is enabled for your Google Cloud project.

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

Verify that billing is enabled for your Google Cloud project.

Abilita le API Artifact Registry, Cloud Run Admin e Cloud Build.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.
Abilita le API

Configura l'ambiente di sviluppo Cloud Run nel tuo progetto Google Cloud .
Assicurati di disporre delle autorizzazioni appropriate per il deployment dei servizi e dei ruoli Amministratore Cloud Run (roles/run.admin) e Utente service account (roles/iam.serviceAccountUser) concessi al tuo account.
Concedi al tuo account il ruolo Cloud Run Invoker (roles/run.invoker). Questo ruolo consente al server MCP remoto di accedere al servizio Cloud Run.

Scopri come concedere i ruoli

Console

Nella console Google Cloud vai alla pagina IAM.
Vai a IAM
Seleziona il progetto.
Fai clic su Concedi l'accesso.
Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email utilizzato per il deployment del servizio Cloud Run.
Nell'elenco Seleziona un ruolo, seleziona un ruolo.
Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.
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: il tuo Google Cloud numero di progetto.
PROJECT_ID: il tuo ID progetto Google Cloud .
PRINCIPAL: l'indirizzo email dell'account a cui stai concedendo il ruolo.
ROLE: il ruolo che stai aggiungendo all'account deployer.

Se il tuo progetto è soggetto a un criterio dell'organizzazione con restrizioni di dominio che limitano le chiamate non autenticate, devi accedere al servizio di cui è stato eseguito il deployment come descritto in Test dei servizi privati.
Installa Uv, un gestore di pacchetti e progetti Python.

Prepara il progetto Python

I passaggi seguenti descrivono come configurare il progetto Python con il uv package manager.

Crea una cartella denominata mcp-on-cloudrun per archiviare il codice sorgente per il deployment:
```
  mkdir mcp-on-cloudrun
  cd mcp-on-cloudrun
```

Crea un progetto Python con lo strumento uv per generare un file pyproject.toml:

  uv init --name "mcp-on-cloudrun" --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.10

Il comando uv init crea il seguente file pyproject.toml:

[project]
name = "mcp-server"
version = "0.1.0"
description = "Example of deploying an MCP server on Cloud Run"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

Crea i seguenti nuovi file aggiuntivi:
- server.py per il codice sorgente del server MCP
- test_server.py per testare il server remoto
- Un Dockerfile per il deployment in Cloud Run
```
touch server.py test_server.py Dockerfile
```
La directory del progetto deve contenere la seguente struttura:
```
├── mcp-on-cloudrun
│   ├── pyproject.toml
│   ├── server.py
│   ├── test_server.py
│   └── Dockerfile
```

Crea un server MCP per le operazioni matematiche

Per fornire un contesto prezioso per migliorare l'utilizzo degli LLM con MCP, configura un server MCP matematico con FastMCP. FastMCP offre un modo rapido per creare server e client MCP con Python.

Segui questi passaggi per creare un server MCP per operazioni matematiche come addizione e sottrazione.

Esegui questo comando per aggiungere FastMCP come dipendenza nel file pyproject.toml:
```
uv add fastmcp==2.13.1 --no-sync
```

Aggiungi il seguente codice sorgente del server MCP matematico al file server.py:

import asyncio
import logging
import os

from fastmcp import FastMCP 

logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

mcp = FastMCP("MCP Server on Cloud Run")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Use this to add two numbers together.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'add' called with numbers '{a}' and '{b}'")
    return a + b

@mcp.tool()
def subtract(a: int, b: int) -> int:
    """Use this to subtract two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The difference of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'subtract' called with numbers '{a}' and '{b}'")
    return a - b

if __name__ == "__main__":
    logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}")
    # Could also use 'sse' transport, host="0.0.0.0" required for Cloud Run.
    asyncio.run(
        mcp.run_async(
            transport="streamable-http",
            host="0.0.0.0",
            port=os.getenv("PORT", 8080),
        )
    )

Includi il seguente codice nel Dockerfile per utilizzare lo strumento uv per eseguire il file server.py:

# Use the official Python image
FROM python:3.13-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Install the project into /app
COPY . /app
WORKDIR /app

# Allow statements and log messages to immediately appear in the logs
ENV PYTHONUNBUFFERED=1

# Install dependencies
RUN uv sync

EXPOSE $PORT

# Run the FastMCP server
CMD ["uv", "run", "server.py"]

Esegui il deployment in Cloud Run

Puoi eseguire il deployment del server MCP come immagine container o come codice sorgente:

Immagine container

Per eseguire il deployment di un server MCP incluso in un pacchetto come immagine container, segui queste istruzioni.

Crea un repository Artifact Registry per archiviare l'immagine container:

gcloud artifacts repositories create remote-mcp-servers \
--repository-format=docker \
--location=us-central1 \
--description="Repository for remote MCP servers" \
--project=PROJECT_ID

Crea l'immagine container ed eseguirne il push su Artifact Registry con Cloud Build:

gcloud builds submit --region=us-central1 --tag us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest

Esegui il deployment dell'immagine contenitore del server MCP su Cloud Run:

gcloud run deploy mcp-server \
--image us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest \
--region=us-central1 \
--no-allow-unauthenticated

Origine

Puoi eseguire il deployment dei server MCP remoti su Cloud Run dalle relative origini.

Esegui il deployment dall'origine eseguendo questo comando:

gcloud run deploy mcp-server --no-allow-unauthenticated --region=us-central1 --source .

Autenticare il client MCP

Se hai eseguito il deployment del servizio con il flag --no-allow-unauthenticated, qualsiasi client MCP che si connette al tuo server MCP remoto deve autenticarsi.

Concedi il ruolo Cloud Run Invoker (roles/run.invoker) al account di servizio. Questo binding dei criteri Identity and Access Management garantisce che venga utilizzato un meccanismo di sicurezza efficace per autenticare il client MCP locale.
Esegui il proxy Cloud Run per creare un tunnel autenticato al server MCP remoto sulla tua macchina locale:
```
gcloud run services proxy mcp-server --region=us-central1
```
Se il proxy Cloud Run non è ancora installato, questo comando ti chiede di scaricarlo. Segui le istruzioni per scaricare e installare il proxy.

Cloud Run autentica tutto il traffico verso http://127.0.0.1:8080 e inoltra le richieste al server MCP remoto.

Testare il server MCP remoto

Testa e connettiti al server MCP remoto utilizzando il client FastMCP e accedendo all'URL http://127.0.0.1:8080/mcp.

Per testare e richiamare il meccanismo di aggiunta e sottrazione, segui questi passaggi:

Prima di eseguire il server di test, esegui il proxy Cloud Run.

Crea un file di test denominato test_server.py e aggiungi il seguente codice:

import asyncio

from fastmcp import Client

async def test_server():
    # Test the MCP server using streamable-http transport.
    # Use "/sse" endpoint if using sse transport.
    async with Client("http://localhost:8080/mcp") as client:
        # List available tools
        tools = await client.list_tools()
        for tool in tools:
            print(f">>> 🛠️  Tool found: {tool.name}")
        # Call add tool
        print(">>> 🪛  Calling add tool for 1 + 2")
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(f"<<< ✅ Result: {result[0].text}")
        # Call subtract tool
        print(">>> 🪛  Calling subtract tool for 10 - 3")
        result = await client.call_tool("subtract", {"a": 10, "b": 3})
        print(f"<<< ✅ Result: {result[0].text}")

if __name__ == "__main__":
    asyncio.run(test_server())

In un nuovo terminale, esegui il server di test:

uv run test_server.py

Dovresti vedere l'output seguente:

 🛠️ Tool found: add
 🛠️ Tool found: subtract
 🪛 Calling add tool for 1 + 2
 ✅ Result: 3
 🪛 Calling subtract tool for 10 - 3
 ✅ Result: 7

Esegui la pulizia

Per evitare addebiti aggiuntivi al tuo account Google Cloud , elimina tutte le risorse che hai implementato con questo tutorial.

Elimina il progetto

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e devi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse che hai creato per il tutorial.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il tutorial.

Per eliminare il progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Nella console Google Cloud , vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona quello che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Elimina le risorse del tutorial

Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial. I servizi Cloud Run non comportano costi finché non ricevono richieste.

Per eliminare il servizio Cloud Run, esegui questo comando:
```
gcloud run services delete SERVICE-NAME
```
Sostituisci SERVICE-NAME con il nome del servizio.

Puoi eliminare i servizi Cloud Run anche dalla consoleGoogle Cloud .
Rimuovi la configurazione della regione predefinita gcloud che hai aggiunto durante la configurazione del tutorial:
```
 gcloud config unset run/region
```
Rimuovi la configurazione del progetto:
```
 gcloud config unset project
```

Crea ed esegui il deployment di un server MCP remoto su Cloud Run Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Obiettivi

Costi

Prima di iniziare

Scopri come concedere i ruoli

Console

gcloud

Prepara il progetto Python

Crea un server MCP per le operazioni matematiche

Esegui il deployment in Cloud Run

Immagine container

Origine

Autenticare il client MCP

Testare il server MCP remoto

Esegui la pulizia

Elimina il progetto

Elimina le risorse del tutorial

Crea ed esegui il deployment di un server MCP remoto su Cloud Run