Bridge MCP

MCP (Model Context Protocol) est un standard ouvert publié par Anthropic en 2024. C'est, en pratique, un format HTTP qui permet à un assistant IA (Claude, ChatGPT, Cursor, etc.) de découvrir et d'appeler des outils externes : lire un calendar, chercher dans une boîte mail, envoyer une notification, etc. Aujourd'hui, la majorité des clients IA grand public et professionnels parlent MCP.

Le bridge MCP de Gilbert expose une partie des capacités de votre workspace, celles qui sont déjà configurées via vos intégrations OAuth (Google, Telegram, LinkedIn, etc.), à ces clients externes. Concrètement : votre client MCP ouvre le flow OAuth Gilbert, vous approuvez les scopes demandés, puis le client appelle /api/mcp avec un access token Bearer. Votre assistant peut alors répondre à « quels sont mes 3 derniers mails ? » ou « qu'est-ce que j'ai cette semaine au calendar ? » en passant par vos tokens Google déjà connectés côté Gilbert.

Le client MCP ne récupère jamais vos refresh tokens Google ou LinkedIn : il reçoit seulement un token Gilbert court-vivant, scopé à MCP. Une fois branché, votre client IA voit la liste des tools disponibles via tools/list et les invoque via tools/call (JSON-RPC 2.0 par-dessus HTTP, streamable).

Le cas d'usage type, qui motive la plupart des installations : vous êtes IT dans une PME, vous avez déployé Gilbert pour l'équipe et configuré les intégrations Google (Gmail / Calendar) au niveau du workspace. Vos collaborateurs utilisent déjà Claude Code ou ChatGPT pour leur travail quotidien. Vous voulez que leur assistant puisse lire leur Gmail et leurCalendar via Gilbert, sans repasser par l'UI Gilbert et sans configurer chaque OAuth Google côté client IA.

Avec le bridge MCP, chaque collaborateur autorise son client favori via OAuth PKCE et bénéficie des intégrations workspace côté Gilbert, strict isolé par utilisateur : le token d'Alice ne voit jamais la boîte mail de Bob, même s'ils partagent le même workspace.

Cinq étapes. Comptez vraiment une minute si vos intégrations OAuth sont déjà connectées.

1. 1. Connecter au moins une intégration OAuth

   Le bridge MCP n'invente rien : il expose ce qui est déjà branché côté Gilbert. Allez sur Console → Mon compte → Intégrations et connectez au minimum Google (Gmail + Calendar) ou Telegram. Sans aucune intégration, votre token MCP fonctionnera mais ne pourra rien lire.

2. 2. Ajouter Gilbert dans le client MCP

   Dans Claude Code, ChatGPT, Cursor ou votre client compatible, ajoutez un serveur MCP HTTP avec cette URL :

   text

   Copier

   https://gilbert.solveholding.com/api/mcp

3. 3. Approuver OAuth PKCE

   Les clients modernes découvrent automatiquement les endpoints OAuth depuis /.well-known/oauth-protected-resource et /.well-known/oauth-authorization-server. Connectez-vous à Gilbert, vérifiez le client et les scopes, puis approuvez. Le client reçoit un access token Bearer d'une heure ; aucun secret long terme n'est copié dans un fichier.

4. 4. Configurer le client MCP

   Choisissez votre client. Tous les exemples utilisent l'URL Gilbert à l'étape 2. La clé solveci-dessous n'est qu'un exemple : renommez ce connecteur selon le nom choisi par votre entreprise.

   Claude CodeCursorCodex CLIn8n / curl

   .mcp.jsonjson

   Copier

   {
     "mcpServers": {
       "solve": {
         "url": "https://gilbert.solveholding.com/api/mcp"
       }
     }
   }

   Pour claude.ai (web) et ChatGPT custom connectors : pas de fichier config, allez dans Settings → Connectors → Add custom (HTTP transport), collez l'URL telle quelle. ChatGPT lit les métadonnées OAuth, ouvre le consent screen Gilbert, puis affiche les tools correspondant aux scopes approuvés.

5. 5. Tester

   Dans votre client, demandez par exemple : « Liste-moi mes 3 derniers mails non lus » ou « Qu'est-ce que j'ai au calendar aujourd'hui ? ». Le client devrait appeler gmail_list_recent ou calendar_list_today et répondre avec vos vraies données.

Gilbert expose les métadonnées OAuth attendues par les clients MCP modernes, dont ChatGPT MCP Apps. Le client part de la ressource https://gilbert.solveholding.com/api/mcp, lit les documents .well-known, enregistre un client public, puis échange un authorization code PKCE contre un access token.

Claude et ChatGPT s'enregistrent tout seuls (Dynamic Client Registration). Gemini Enterprise ne le fait pas : son connecteur « Custom MCP Server » attend un client OAuth confidentiel pré-enregistré (un client_id + un client_secretque l'admin colle dans la console Google). Gilbert génère ce client en self-serve.

1. 1. Générer le connecteur (admin workspace)

   Allez sur Console → Workspaces → [votre workspace] → Connecteurs IA, cliquez « Générer un connecteur ». Le client_secret s'affiche une seule fois : copiez-le immédiatement. Le client est scopé à ce workspace.

2. 2. Coller dans Gemini Enterprise

   Google Cloud console → Gemini Enterprise → Data stores → Create data store → « Custom MCP Server (Preview) ». Collez :

   text

   Copier

   MCP Server URL    : https://gilbert.solveholding.com/api/mcp
   Authorization URL : https://gilbert.solveholding.com/api/oauth/authorize
   Token URL         : https://gilbert.solveholding.com/api/oauth/token
   Client ID         : (généré à l'étape 1)
   Client Secret     : (généré à l'étape 1, affiché une fois)
   Scopes            : mcp:read mcp:write workspace:read mcp:destructive offline_access
   Redirect URI      : https://vertexaisearch.cloud.google.com/oauth-redirect

   mcp:destructivepeut être demandé explicitement ici (client confidentiel pré-enregistré) : il apparaîtra dans la liste des scopes sur l'écran de consentement. Ne l'incluez pas si ce connecteur ne doit jamais envoyer de mail ni poster en votre nom.

3. 3. Autoriser

   Le bouton « Login » du connecteur ouvre le consent screen Gilbert. L'utilisateur qui autorise doit avoir un compte Gilbert membre de ce workspace (le consentement passe par /login). La connexion atterrit dans le workspace du connecteur, pas ailleurs. Si le connecteur doit pouvoir envoyer des mails, répondre aux invitations ou poster sur Slack, cochez aussi « Autoriser les actions » sur cet écran : c'est elle, et non le scope demandé ci-dessus, qui décide en dernier ressort si mcp:destructive est accordé.

Les scopes sont portés par le token OAuth. tools/list masque les tools que le token ne peut pas appeler ; tools/call refuse avec Missing required scope si un scope manque.

Étapes exactes pour envoyer votre premier mail via MCP, du consentement à l'exécution confirmée.

1. 1. Connecter Google

   Si ce n'est pas déjà fait : Console → Mon compte → Intégrations, connectez Gmail.

2. 2. Cocher « Autoriser les actions » au consentement

   Lors de l'étape « Approuver OAuth PKCE » du setup ci-dessus, l'écran de consentement Gilbert affiche une case décochée par défaut : « Autoriser les actions (envoi de mails, invitations, posts) ». Cochez-la avant de cliquer sur « Autoriser ». Sans cette case, mcp:destructive n'est jamais accordé, même si votre client l'avait demandé dans son scope.

3. 3. Ouvrir une NOUVELLE conversation

   Un client MCP lit généralement la liste des tools une fois par session. Démarrez une nouvelle conversation dans votre client pour qu'il rappelle tools/list et voie apparaître gmail_send et les autres destructifs.

4. 4. Demander « envoie un mail test »

   Le client appelle gmail_send. La réponse n'est pas un mail envoyé : c'est un texte qui décrit l'action proposée et contient une ligne pending_action_id: …. Rien n'est parti.

5. 5. Approuver côté client, puis confirm_action

   L'annotation MCP destructiveHint est portée par confirm_action(pas par gmail_send lui-même, qui ne fait que proposer) : un client conforme (claude.ai) affiche sa propre UI d'approbation avant d'appeler confirm_action. Une fois que vous approuvez, le client appelle confirm_action({id, action:'confirm'}) : Gilbert exécute réellement l'envoi et répond avec l'id du mail parti. Pour refuser sans rien exécuter : confirm_action({id, action:'abort'}). Sans confirmation ni annulation, l'action expire au bout de 10 minutes.

Liste des tools accessibles via un token personnel. La plupart sont en lecture seule, notification ou écriture non destructive (brouillon, création de routine). Les tools qui écrivent ou émettent réellement côté tiers (envoi de mail, RSVP calendar, post Slack…) sont marqués destructif dans la colonne Scope : ils exigent le scope mcp:destructiveet ne s'exécutent jamais directement, voir confirm_action plus bas. La colonne Intégration requiseindique quel OAuth doit être connecté côté Gilbert pour que le tool fonctionne, sinon il retourne une erreur explicite demandant à l'utilisateur de connecter l'intégration.

Trois tools administratifs supplémentaires (provision_workspace, seed_workspace_routines, generate_commercial_offer) sont exposés via MCP mais gated à un caller admin d'au moins un workspace Solve : ils servent aux routines commerciales internes (provisioning de workspaces prospects). Vous ne les croiserez pas en usage standard. provision_workspacecrée toujours un workspace hors de tout périmètre choisi à l'écran de consentement (il n'existait pas encore au moment d'autoriser le connecteur) : il est donc refusé pour tout token dont l'allowlist est restreinte à un sous-ensemble de workspaces, même si le caller est admin Solve. L'écran de consentement rejette désormais une sélection vide dès qu'au moins un workspace est accessible, donc un token non restreint ne peut plus s'obtenir via le picker de cases à cocher — seule une clé legacy (personnelle ou workspace, jamais soumise à cette allowlist) permet d'appeler ce tool aujourd'hui.

Trois invariants tiennent l'ensemble du bridge :

• Bearer court-vivant.Le client reçoit un access token Gilbert d'une heure, pas les refresh tokens Google/LinkedIn. Les authorization codes sont à usage unique et expirent en 10 minutes.
• Scopé au user qui l'a approuvé + à l'allowlist de workspace(s) coché(s) à l'écran de consentement. Un token personnel d'Alice ne donne accès qu'à la boîte mail d'Alice, son calendar, ses routines. Même si Bob est dans le même workspace, son token à lui voit uniquement ses données. Isolation cross-user garantie par RLS Postgres côté schema gilbert. Côté workspace, cette allowlist est appliquée serveur à chaque tool de découverte/action, au chemin direct-id de run_routine et au handshake initialize: un token restreint à un sous-ensemble ne peut jamais atteindre un workspace hors périmètre, même si l'user en devient membre plus tard sans re-consentement.
• Pas de secrets dans les outputs discovery. Les tools workspace ne retournent ni API keys, ni tokens OAuth, ni signing secrets, ni prompts internes. Ils filtrent toujours par membership du user authentifié.

publish_linkedin_post est exposé via MCP avec un confirm-flow obligatoire. Deux remparts indépendants protègent contre la publication non-souhaitée :

1. 1. Confirm-flow côté client AI (description « ask first »)

   La description du tool exige que le client AI (Claude, ChatGPT, Cursor) demande confirmation explicite à l'utilisateur avant de l'appeler, en montrant un preview du texte exact et en n'invoquant le tool que si l'utilisateur répond « oui » / « go » / « publie ». Cette convention couvre le cas d'usage légitime (Martin via Claude Code) : Claude demande « OK pour poster ? » et exécute le tool si l'utilisateur confirme.

2. 2. Délai serveur de 5 min + commande Telegram /cancel-linkedin

   Une fois le tool appelé, la publication n'est pas instantanée. Le serveur Gilbert programme l'action dans 5 minutes (insertion dans personal_pending_actions avec status='scheduled' et scheduled_at=now()+5min) et envoie immédiatement une notification Telegram à l'utilisateur avec un preview du texte + la commande /cancel-linkedin <action_id>.

   Si l'utilisateur répond avec la commande dans la fenêtre, l'action passe à canceled et la publication ne part pas. Sans action, le worker /api/cron/pending-actions-tick exécute la publication une fois scheduled_at dépassé.

Les actions qui écrivent ou émettent réellement côté tiers (envoi de mail, réponse à une invitation calendar, création d'événement, post Slack, création de routine récurrente) sont exposées via MCP, mais aucune ne s'exécute directement : l'appel initial (gmail_send, calendar_respond, calendar_create_event, slack_post_to_channel, create_scheduled_draft) crée une action en attente (personal_pending_actions, TTL 10 minutes) et renvoie un texte contenant une ligne pending_action_id: …. Le client doit repasser cet id à confirm_actionpour que quoi que ce soit s'exécute réellement : c'est la même barrière humaine que le rituel « ok »/« annule » du chat Gilbert, portée côté MCP par l'annotation destructiveHint sur confirm_action (pas sur le tool destructif lui-même, qui ne fait que proposer). Voir le walkthrough plus haut pour un exemple complet.

confirm_action accepte deux actions :

• action:'confirm' exécute réellement l'action proposée (idempotent : rappeler confirm avec le même id déjà exécuté renvoie le même résultat sans ré-exécuter).
• action:'abort'annule l'action sans rien exécuter.
• Sans confirmation ni annulation dans la fenêtre de 10 minutes, l'action expire: elle n'est jamais exécutée automatiquement. Un id inconnu, déjà traité, ou appartenant à une autre origine/utilisateur retourne not_found: ré-invoquez le tool d'origine pour reproposer l'action (avec un nouvel id de confirmation).

publish_linkedin_post reste exposé avec son propre mécanisme (confirm-flow côté client AI + délai serveur de 5 minutes annulable via Telegram, pas confirm_action), voir section dédiée plus bas.

Le scope mcp:destructiveest nouveau (12 juillet 2026). Les connexions MCP existantes, personnelles ou connecteurs Gemini Enterprise, ne l'ont pas : il n'y a pas d'octroi rétroactif. Sans reconnexion, gmail_send et les autres destructifs restent simplement absents de tools/list pour ces tokens.

1. 1. Token personnel (Claude, ChatGPT, Cursor, Codex…)

   Reconnectez le serveur MCP depuis votre client (déconnecter puis reconnecter Gilbert, ou révoquer la clé depuis Console → Mon compte → Bridge MCP) pour redéclencher le flow OAuth complet.

2. 2. Cocher « Autoriser les actions »

   Sur l'écran de consentement qui s'affiche, cochez « Autoriser les actions (envoi de mails, invitations, posts) » avant de cliquer sur « Autoriser ». C'est la seule voie d'acquisition de mcp:destructive: le scope n'est pas dans la liste publiquement annoncée, un client ne peut pas l'obtenir simplement en le demandant.

3. 3. Connecteur Gemini Enterprise (workspace)

   Un admin ajoute mcp:destructive aux scopes du connecteur (Google Cloud console → Gemini Enterprise → Data stores → connecteur Gilbert) puis relance le flow « Login » : l'utilisateur qui consent doit cocher la même case « Autoriser les actions ».

4. 4. Nouvelle conversation pour rafraîchir tools/list

   Une session déjà ouverte a mis en cache l'ancienne liste de tools. Démarrez une nouvelle conversation pour que le client rappelle tools/list et voie apparaître les destructifs.

5. 5. Legacy key auth (?key=glb_…)

   Les anciennes clés (feature flag mcp_legacy_key_auth) ont des scopes figés à la création et ne peuvent jamais obtenir mcp:destructive. Migrez vers OAuth pour débloquer les actions.

• 401 invalid_token : le token Bearer est absent, expiré ou révoqué. La réponse inclut un header WWW-Authenticate avec l'URL de discovery OAuth ; relancez le flow de connexion du client. ChatGPT custom connectors sait reprendre automatiquement après le callback OAuth.
• Missing required scope: … : le token a été autorisé sans le scope demandé. Relancez OAuth avec mcp:read pour lister les tools, mcp:write pour les appeler, workspace:read pour découvrir workspaces/routines/membres, ou mcp:destructive pour les tools qui envoient/écrivent réellement (voir la section Migration : reconnecter pour débloquer les actions ci-dessus : ce dernier ne s'obtient qu'en cochant « Autoriser les actions » au consentement, pas en le demandant simplement dans le scope).
• -32602 Unknown tool: … : le tool n'existe pas sous ce nom dans le registry. Un tool qui existe mais est hors du scope de votre token retourne Missing required scope (voir ci-dessus), pas Unknown tool. Une clé workspace qui appelle un tool réservé aux clés personnelles reçoit un message dédié l'indiquant explicitement (« requires user-scope MCP key »).
• workspace_not_found / forbidden : le workspaceIddemandé n'est pas accessible au user authentifié, ou est en dehors du périmètre de workspace(s) choisi à l'écran de consentement OAuth pour ce token : réautorisez le connecteur en cochant ce workspace pour l'ajouter au périmètre. list_workspace_members exige en plus le rôle admin sur ce workspace.
• Erreur Google: missing_integration / revoked : l'intégration Google a été déconnectée ou son refresh token a expiré. Reconnectez Google depuis Console → Mon compte → Google (force consent recommandé). Pareil pour LinkedIn / Telegram : chacun a sa page de reconnexion.
• 429 rate_limit : vous avez dépassé 10 rotations de clé par minute sur la même IP. C'est une protection anti-abuse côté /api/personal/api-key/rotate, sans impact en usage normal. Attendez 60s avant la prochaine rotation.
• Le client ne voit aucun tool : vérifiez que vous avez bien configuré le transport HTTP (et non stdio). Le bridge Gilbert est exclusivement HTTP streamable. Si votre client ne supporte que stdio, mettez un wrapper léger (ex. mcp-remote côté npm) qui fait le pont stdio ↔ HTTP.

• Intégrations OAuth : connecter Google, Telegram, LinkedIn, GitHub à votre workspace. C'est le pré-requis pour que le token MCP ait quelque chose à exposer.
• Routines : bridge bidirectionnel. Les routines Gilbert avec execution_mode=client tournent en background tasks Claude Code, ack via mark_task_synced, et routent les replies Telegram vers la session active. Le provider LLM est indépendant : server ou client, anthropic ou google. Pour qui veut automatiser via cron plutôt que par chat.
• Webhooks : voie d'entrée alternative côté serveur, pour les events Gilbert (dossier qualifié, PR ouverte, etc.) HMAC-signés vers vos endpoints. Complémentaire au bridge MCP (qui est, lui, une voie de sortie côté client IA).