Héberger des serveurs MCP sur Cloud Run

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

MCP est un protocole ouvert qui normalise 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 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 en streaming, 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 normalisé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 d'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.

Avant de commencer

  1. Connectez-vous à votre Google Cloud compte. Si vous ne connaissez pas Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. 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 Google Cloud projet.
  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 Add another role , puis ajoutez chaque rôle supplémentaire.
    7. Cliquez sur Enregistrer.

    gcloud

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

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

    Remplacez :

    • PROJECT_NUMBER par le numéro de votre Google Cloud projet
    • PROJECT_ID par l'ID de votre Google Cloud projet.
    • PRINCIPAL par le compte pour lequel vous ajoutez la liaison. Il s'agit généralement de l'adresse e-mail qui est utilisée pour déployer le service Cloud Run.
    • ROLE par le rôle que vous ajoutez au compte du déployeur.

Héberger des serveurs MCP SSE ou HTTP en streaming distants

Les serveurs MCP qui utilisent les événements envoyés par le serveur (SSE) ou le transport HTTP en streaming 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 il 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 qu'ils 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, notamment 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-le 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, le serveur MCP reçoit une URL HTTPS et la communication peut utiliser la prise en charge intégrée de Cloud Run pour 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 IAM "Demandeur"

Par défaut, l'URL des services Cloud Run exige 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é renforcé 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 machine locale 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 Google Cloud région dans laquelle vous avez déployé votre service. Par exemple, europe-west1.

La commande de 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 mcp-remote package npm :

{
  "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 d'authentification Google pour Python. Ce jeton doit comporter la revendication d'audience correcte qui correspond à l'URL du service de réception *.run.app, sauf si vous utilisez des audiences personnalisées. Vous devez également inclure le jeton d'ID dans les requêtes client, par exemple Authorization: Bearer <token value>.

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

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 où le client MCP s'exécute.

Aucune authentification spécifique n'est requise pour ce cas d'utilisation, car le client 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 le service auprès du service

Si le serveur et le client MCP s'exécutent en tant que services Cloud Run distincts, consultez la section Authentifier un service auprès d'un autre.

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 la gestion du trafic.

Vous pouvez configurer le service de 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.

Étape suivante