Héberger des serveurs MCP sur Cloud Run

Ce guide explique comment héberger un serveur Model Context Protocol (MCP) avec un transport HTTP diffusable sur Cloud Run, et fournit des conseils pour authentifier les clients MCP. Si vous ne connaissez pas MCP, lisez les ressources suivantes :

MCP est un protocole ouvert qui standardise la façon dont les agents IA interagissent avec leur environnement. L'agent IA héberge un client MCP, et les outils et ressources avec lesquels il interagit sont des serveurs MCP. Le client MCP peut communiquer avec le serveur MCP via deux types de transport distincts :

Vous pouvez héberger des clients et des serveurs MCP sur la même machine locale, héberger un client MCP localement et le faire communiquer avec des serveurs MCP distants hébergés sur une plate-forme cloud comme Cloud Run, ou héberger à la fois le client et le serveur MCP sur une plate-forme cloud.

Cloud Run est compatible avec l'hébergement de serveurs MCP avec transport HTTP diffusable, mais pas avec les serveurs MCP avec transport stdio.

Le schéma suivant montre comment le client MCP prend l'intention de l'agent IA et envoie une requête standardisée aux serveurs MCP, en spécifiant l'outil à exécuter. Une fois que le serveur MCP a exécuté l'action et récupéré les résultats, il les renvoie au client MCP dans un format cohérent.

Un serveur MCP interagit avec un agent IA via un client MCP.
Figure 1.Le serveur MCP hébergé sur Cloud Run interagit avec le client MCP, qui interagit avec l'agent IA.

Les conseils de cette page s'appliquent si vous développez votre propre serveur MCP ou si vous utilisez un serveur MCP existant.

  • Si vous développez votre propre serveur MCP, nous vous recommandons d'utiliser un SDK de serveur MCP, tel que les SDK de langage officiels (TypeScript, Python, Go, Kotlin, Java, C#, Ruby ou Rust) ou FastMCP.
  • Si vous utilisez un serveur MCP existant, vous trouverez une liste des serveurs MCP officiels et de la communauté dans le dépôt GitHub des serveurs MCP. Docker Hub fournit également une liste de serveurs MCP.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  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. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
  7. Assurez-vous de disposer des autorisations appropriées pour déployer des services, et que les rôles Administrateur Cloud Run (roles/run.admin) et Utilisateur du compte de service (roles/iam.serviceAccountUser) sont attribués à votre compte.

    8. Découvrez comment attribuer les rôles.

    Console

    1. Dans la console Google Cloud , accédez à la page IAM.

      Accéder à IAM
    2. Sélectionnez le projet.
    3. Cliquez sur  Accorder l'accès.

    4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail utilisée pour déployer le service Cloud Run.

    5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
    6. Pour attribuer des rôles supplémentaires, cliquez sur Ajouter un autre rôle et ajoutez tous les rôles supplémentaires requis.
    7. Cliquez sur Enregistrer.

    gcloud

    Pour attribuer les rôles IAM requis à votre compte sur votre projet :

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

    Remplacez :

    • PROJECT_NUMBER par votre numéro de projet Google Cloud .
    • PROJECT_ID par l'ID de votre projet Google Cloud .
    • PRINCIPAL par le compte pour lequel vous ajoutez la liaison. Il s'agit généralement de l'adresse e-mail utilisée pour déployer le service Cloud Run.
    • ROLE par le rôle que vous ajoutez au compte de déploiement.
  8. Consultez la grille tarifaire de Cloud Run ou estimez les coûts à l'aide du simulateur de coût.

Héberger des serveurs MCP SSE ou HTTP diffusables à distance

Les serveurs MCP qui utilisent les événements envoyés par le serveur (SSE) ou le transport HTTP en flux continu peuvent être hébergés à distance de leurs clients MCP.

Pour déployer ce type de serveur MCP sur Cloud Run, vous pouvez le déployer en tant qu'image de conteneur ou en tant que code source (généralement Node.js ou Python), selon la façon dont le serveur MCP est empaqueté.

Images de conteneurs

Les serveurs MCP distants distribués en tant qu'images de conteneur sont des serveurs Web qui écoutent les requêtes HTTP sur un port spécifique. Cela signifie qu'ils respectent le contrat d'exécution de conteneur de Cloud Run et peuvent être déployés sur un service Cloud Run.

Pour déployer un serveur MCP empaqueté en tant qu'image de conteneur, vous devez disposer de l'URL de l'image de conteneur et du port sur lequel il s'attend à recevoir des requêtes. Vous pouvez les déployer à l'aide de la commande gcloud CLI suivante :

gcloud run deploy --image IMAGE_URL --port PORT

Remplacez :

  • IMAGE_URL par l'URL de l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/mcp.
  • PORT par le port sur lequel il écoute, par exemple 3000.

Sources

Les serveurs MCP distants qui ne sont pas fournis en tant qu'images de conteneur peuvent être déployés sur Cloud Run à partir de leurs sources, en particulier s'ils sont écrits en Node.js ou en Python.

  1. Clonez le dépôt Git du serveur MCP : 

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

  2. Accédez à la racine du serveur MCP : 

    cd REPOSITORY

  3. Déployez sur Cloud Run à l'aide de la commande gcloud CLI suivante : 

    gcloud run deploy --source .

Une fois que vous avez déployé votre serveur MCP HTTP sur Cloud Run, il obtient une URL HTTPS et la communication peut utiliser la compatibilité intégrée de Cloud Run avec le streaming de réponses HTTP.

Authentifier les clients MCP pour les agents IA

Selon l'endroit où vous avez hébergé le client MCP, consultez la section qui vous concerne :

Authentifier les clients MCP locaux

Si l'agent IA hébergeant le client MCP s'exécute sur une machine locale, utilisez l'une des méthodes suivantes pour authentifier le client MCP :

Pour en savoir plus, consultez la spécification MCP sur l'authentification.

Autorisation d'appelant IAM

Par défaut, l'URL des services Cloud Run nécessite que toutes les requêtes soient autorisées avec le rôle IAM Demandeur Cloud Run (roles/run.invoker). Cette liaison de stratégie IAM garantit qu'un mécanisme de sécurité robuste est utilisé pour authentifier votre client MCP local.

Après avoir déployé votre serveur MCP sur un service Cloud Run dans une région, exécutez le proxy Cloud Run sur votre ordinateur local pour exposer de manière sécurisée le serveur MCP distant à votre client à l'aide de vos propres identifiants :

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

Remplacez :

  • MCP_SERVER_NAME par le nom de votre service Cloud Run.
  • REGION par la région Google Clouddans laquelle vous avez déployé votre service. Par exemple, europe-west1.

La commande du proxy Cloud Run crée un proxy local sur le port 3000 qui transfère les requêtes au serveur MCP distant et injecte votre identité.

Mettez à jour le fichier de configuration MCP de votre client MCP avec les éléments suivants :

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

Si votre client MCP n'est pas compatible avec l'attribut url, utilisez le package npm mcp-remote :

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

Jeton d'ID OIDC

Selon que le client MCP expose des en-têtes ou utilise un moyen de fournir un transport authentifié personnalisé, vous pouvez envisager d'authentifier le client MCP avec un jeton d'ID OIDC.

Vous pouvez utiliser différentes bibliothèques d'authentification Google pour obtenir un jeton d'ID à partir de l'environnement d'exécution, par exemple la bibliothèque Google Auth pour Python. Ce jeton doit comporter la revendication d'audience appropriée qui correspond à l'URL *.run.app du service destinataire, sauf si vous utilisez des audiences personnalisées. Vous devez également inclure le jeton d'ID dans les requêtes client, telles que Authorization: Bearer <token value>.

Si le client MCP n'expose ni les en-têtes, ni le transport, utilisez une autre méthode d'authentification.

Authentifier les clients MCP locaux avec IAP

Cette section explique comment authentifier les clients MCP locaux qui s'exécutent sur Cloud Run.

Pour créer la règle d'entrée, procédez comme suit :

  1. Attribuez le rôle Demandeur Cloud Run (roles/run.invoker) à l'agent de service IAP.

    gcloud run services add-iam-policy-binding SERVICE_NAME \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com' \
    --role='roles/run.invoker'

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom du service auquel ajouter la liaison de stratégie

    • PROJECT_NUMBER : numéro du projet contenant le service.

  2. Activez IAP sur le service Cloud Run.

    Créer

    Pour activer l'authentification IAP pour un nouveau service, exécutez la commande suivante :

    gcloud run deploy SERVICE_NAME --image=MCP_SERVER_IMAGE
  --functional-type=MCP_SERVER \
  --region=REGION \
  --iap

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom du service auquel ajouter la liaison de stratégie

    • MCP_SERVER_IMAGE : chemin d'accès de l'image du serveur MCP

    • REGION : région Google Cloud dans laquelle vous souhaitez déployer votre service, par exemple europe-west1

    Mettre à jour

    Pour activer l'authentification IAP pour un service existant, exécutez la commande suivante :

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

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom du service à mettre à jour.

    • REGION : région Google Cloud dans laquelle vous avez déployé votre service, par exemple europe-west1

Authentifier les clients MCP exécutés sur Cloud Run

Si l'agent IA hébergeant le client MCP s'exécute sur Cloud Run, utilisez l'une des méthodes suivantes pour authentifier le client MCP :

Déployer le serveur MCP en tant que side-car

Le serveur MCP peut être déployé en tant que side-car là où le client MCP s'exécute.

Aucune authentification spécifique n'est requise pour ce cas d'utilisation, car le client MCP et le serveur MCP se trouvent sur la même instance. Le client peut se connecter au serveur MCP à l'aide d'un port sur http://localhost:PORT. Remplacez PORT par un port différent de celui utilisé pour envoyer des requêtes au service Cloud Run.

Authentifier les requêtes de service à service

Si le serveur MCP et le client MCP s'exécutent en tant que services Cloud Run distincts, consultez Authentification de service à service.

Utiliser Cloud Service Mesh

Un agent hébergeant un client MCP peut se connecter à un serveur MCP distant à l'aide de Cloud Service Mesh. L'utilisation d'un maillage de services simplifie l'orchestration des microservices en gérant automatiquement l'authentification et le trafic.

Vous pouvez configurer le service du serveur MCP pour qu'il ait un nom court sur le maillage, et le client MCP peut communiquer avec le serveur MCP à l'aide du nom court http://mcp-server. L'authentification est gérée par le maillage.

Étapes suivantes