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 débutez avec MCP, consultez le guide d'introduction pour en savoir plus.

MCP est un protocole ouvert qui normalise la façon dont les agents d'IA interagissent avec leur environnement. L'agent d'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 permet d'héberger des serveurs MCP avec un transport HTTP en flux continu, mais pas des serveurs MCP avec un transport stdio.

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. 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. 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) vous ont été attribués.

    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 du compte Google utilisé 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 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 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 du compte Google utilisé pour déployer le service Cloud Run.
    • ROLE par le rôle que vous ajoutez au compte de déploiement.

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

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

    Pour déployer ce type de serveur MCP sur Cloud Run, vous pouvez déployer le serveur MCP 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 à distance distribués sous forme d'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é sous forme d'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 déployer ces fichiers à 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 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 avec la commande gcloud CLI suivante : 

      gcloud run deploy --source .

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

    Authentifier les clients MCP

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

    Authentifier les clients MCP locaux

    Si l'agent d'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é 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 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 région dans laquelle vous avez déployé votre service. Google CloudPar 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 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'identité OIDC.

    Vous pouvez utiliser différentes bibliothèques d'authentification Google pour obtenir un jeton d'identification à partir de l'environnement d'exécution, par exemple la bibliothèque Google Auth pour Python. Ce jeton doit comporter la revendication d'audience correcte correspondant à l'URL *.run.app du service destinataire, sauf si vous utilisez des audiences personnalisées. Vous devez également inclure le jeton d'identité 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 exécutés sur Cloud Run

    Si l'agent d'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ù s'exécute le client MCP.

    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 de service à service

    Si le serveur 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.

    Vous pouvez configurer le service de serveur MCP pour qu'il ait un nom court sur le maillage. 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 réseau maillé.

    Étapes suivantes