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 les ressources suivantes :

MCP est un protocole ouvert qui standardise la façon dont les agents 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 à 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 en flux continu, 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 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 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) 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 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.
    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 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 diffusables à 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 fonctions à 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 utiliser la compatibilité intégrée de Cloud Run avec le streaming de réponses HTTP.

Authentifier les clients MCP pour les agents d'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 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ù 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 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. 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. 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