MCP

openclaw mcp remplit deux fonctions :

• exécuter OpenClaw en tant que serveur MCP avec openclaw mcp serve
• gérer les définitions de serveurs MCP sortants administrées par OpenClaw avec list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload et unset

Avec serve, OpenClaw agit en tant que serveur MCP. Avec les autres sous-commandes, OpenClaw agit en tant que registre côté client MCP pour les serveurs que ses propres environnements d’exécution pourront utiliser ultérieurement.

Utilisez openclaw acp lorsqu’OpenClaw doit héberger lui-même une session d’environnement de développement et acheminer cet environnement d’exécution via ACP.

Choisir le bon mode d’utilisation de MCP

OpenClaw en tant que serveur MCP

Il s’agit du mode openclaw mcp serve.

Quand utiliser serve

Utilisez openclaw mcp serve lorsque :

• Codex, Claude Code ou un autre client MCP doit communiquer directement avec des conversations de canaux prises en charge par OpenClaw
• vous disposez déjà d’un Gateway OpenClaw local ou distant avec des sessions acheminées
• vous souhaitez utiliser un serveur MCP unique fonctionnant avec tous les systèmes de canaux d’OpenClaw, plutôt que d’exécuter des ponts distincts pour chaque canal

Utilisez plutôt openclaw acp lorsqu’OpenClaw doit héberger lui-même l’environnement d’exécution de développement et conserver la session de l’agent dans OpenClaw.

Fonctionnement

openclaw mcp serve démarre un serveur MCP stdio. Le client MCP est propriétaire de ce processus. Tant que le client maintient la session stdio ouverte, le pont se connecte à un Gateway OpenClaw local ou distant via WebSocket et expose les conversations de canaux acheminées via MCP.

Choisir un mode client

Éléments exposés par serve

Le pont utilise les métadonnées existantes d’acheminement des sessions du Gateway pour exposer les conversations prises en charge par les canaux. Une conversation apparaît lorsqu’OpenClaw possède déjà un état de session avec un itinéraire connu, tel que :

• channel
• les métadonnées du destinataire ou de la destination
• un accountId facultatif
• un threadId facultatif

Les clients MCP disposent ainsi d’un emplacement unique pour :

• répertorier les conversations récentes acheminées
• lire l’historique récent des transcriptions
• attendre de nouveaux événements entrants
• renvoyer une réponse via le même itinéraire
• voir les demandes d’approbation reçues tant que le pont est connecté

Utilisation

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verboseopenclaw mcp serve --claude-channel-mode off

Outils du pont

Modèle d’événements

Le pont conserve une file d’attente d’événements en mémoire tant qu’il est connecté.

Types d’événements actuels :

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

Notifications de canal Claude

Le pont peut également exposer des notifications de canal propres à Claude. Il s’agit de l’équivalent OpenClaw d’un adaptateur de canal Claude Code : les outils MCP standard restent disponibles, mais les messages entrants en direct peuvent également arriver sous forme de notifications MCP propres à Claude.

Lorsque le mode de canal Claude est activé, le serveur annonce les fonctionnalités expérimentales de Claude et peut émettre :

• notifications/claude/channel
• notifications/claude/channel/permission

Comportement actuel du pont :

• les messages de transcription user entrants sont transmis sous forme de notifications/claude/channel
• les demandes d’autorisation Claude reçues via MCP sont suivies en mémoire
• si le propriétaire de la commande dans la conversation liée envoie ensuite yes <id> ou no <id> (<id> est l’identifiant de demande à 5 lettres, sans l), le pont convertit ce message en notifications/claude/channel/permission
• ces notifications n’existent que pendant la session active ; si le client MCP se déconnecte, aucune cible push n’est disponible

Ce comportement est volontairement propre au client. Les clients MCP génériques doivent s’appuyer sur les outils d’interrogation standard.

Configuration du client MCP

Exemple de configuration d’un client stdio :

{  "mcpServers": {    "openclaw": {      "command": "openclaw",      "args": [        "mcp",        "serve",        "--url",        "wss://gateway-host:18789",        "--token-file",        "/path/to/gateway.token"      ]    }  }}

Pour la plupart des clients MCP génériques, commencez par l’ensemble d’outils standard et ignorez le mode Claude. Activez le mode Claude uniquement pour les clients qui prennent réellement en charge les méthodes de notification propres à Claude.

Options

openclaw mcp serve prend en charge :

Sécurité et frontière de confiance

Le pont n’invente pas le routage. Il expose uniquement les conversations que le Gateway sait déjà acheminer.

Cela signifie que :

• les listes d’expéditeurs autorisés, l’association et la confiance au niveau du canal relèvent toujours de la configuration du canal OpenClaw sous-jacent
• messages_send peut uniquement répondre par l’intermédiaire d’une route existante enregistrée
• l’état des approbations est actif et conservé uniquement en mémoire pour la session actuelle du pont
• l’authentification du pont doit utiliser les mêmes contrôles de jeton ou de mot de passe du Gateway que ceux auxquels vous feriez confiance pour tout autre client distant du Gateway

Si une conversation est absente de conversations_list, la cause habituelle n’est pas la configuration MCP. Il s’agit de métadonnées de routage manquantes ou incomplètes dans la session du Gateway sous-jacente.

Tests

OpenClaw fournit un test de fumée Docker déterministe pour ce pont :

pnpm test:docker:mcp-channels

Ce test de fumée exécute un seul conteneur : il initialise l’état des conversations, démarre le Gateway, puis lance openclaw mcp serve comme processus enfant stdio et le pilote en tant que client MCP. Il vérifie la découverte des conversations, la lecture des transcriptions, la lecture des métadonnées des pièces jointes, le comportement de la file d’événements en direct, ainsi que les notifications de canal et d’autorisation de style Claude sur le véritable pont MCP stdio. Le routage des envois sortants (messages_send réutilisant la route de conversation enregistrée) est couvert séparément par les tests unitaires dans src/mcp/channel-server.test.ts.

C’est le moyen le plus rapide de prouver que le pont fonctionne sans intégrer un véritable compte Telegram, Discord ou iMessage à l’exécution du test.

Pour un contexte de test plus général, consultez Tests.

Résolution des problèmes

OpenClaw comme registre de clients MCP

Il s’agit du parcours openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload et unset.

Ces commandes n’exposent pas OpenClaw via MCP. Elles gèrent les définitions de serveurs MCP administrées par OpenClaw sous mcp.servers dans la configuration d’OpenClaw. Elles ne lisent pas les serveurs mcporter depuis config/mcporter.json.

Ces définitions enregistrées sont destinées aux environnements d’exécution qu’OpenClaw lancera ou configurera ultérieurement, comme OpenClaw intégré et d’autres adaptateurs d’environnement d’exécution. OpenClaw stocke les définitions de manière centralisée afin que ces environnements d’exécution n’aient pas à conserver leurs propres listes de serveurs MCP en double.

Les adaptateurs d’environnement d’exécution peuvent normaliser ce registre partagé selon la forme attendue par leur client en aval. Par exemple, OpenClaw intégré consomme directement les valeurs transport d’OpenClaw, tandis que Claude Code et Gemini reçoivent des valeurs type natives de la CLI, telles que http, sse ou stdio.

Le serveur d’application Codex respecte également un bloc facultatif codex sur chaque serveur. Il s’agit de métadonnées de projection OpenClaw réservées aux fils de discussion du serveur d’application Codex ; elles ne modifient pas les sessions ACP, la configuration générique du harnais Codex ni les autres adaptateurs d’environnement d’exécution. Utilisez une valeur codex.agents non vide pour projeter un serveur uniquement dans des identifiants d’agents OpenClaw précis. Les listes d’agents vides, ne contenant que des espaces ou non valides sont rejetées par la validation de la configuration et omises par le parcours de projection de l’environnement d’exécution au lieu de devenir globales. Utilisez codex.defaultToolsApprovalMode (auto, prompt ou approve) pour émettre la valeur native default_tools_approval_mode de Codex pour un serveur de confiance. OpenClaw supprime les métadonnées codex avant de transmettre la configuration native mcp_servers à Codex.

Définitions de serveurs MCP enregistrées

Commandes :

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

Remarques :

• list trie les noms des serveurs.
• show sans nom affiche l’objet complet des serveurs MCP configurés.
• status classe les transports configurés sans se connecter. --verbose inclut les détails résolus du lancement, des délais d’expiration, d’OAuth, des filtres et des appels parallèles.
• doctor effectue des vérifications statiques sans se connecter. Ajoutez --probe lorsque la commande doit également vérifier que les serveurs activés peuvent se connecter.
• probe se connecte et signale le nombre d’outils, la prise en charge des ressources et invites, la prise en charge des changements de liste et les diagnostics.
• add accepte des options stdio telles que --command, --arg, --env et --cwd, ou des options HTTP telles que --url, --transport, --header, --auth oauth, ainsi que des options TLS, de délai d’expiration et de sélection des outils.
• set attend une valeur d’objet JSON sur la ligne de commande.
• configure met à jour l’activation, les filtres d’outils, les délais d’expiration, OAuth, TLS et les indications d’appels d’outils parallèles sans remplacer la définition complète du serveur. Ajoutez --probe pour vérifier le serveur mis à jour avant l’enregistrement.
• tools met à jour les filtres d’outils par serveur. Les entrées d’inclusion et d’exclusion sont des noms d’outils MCP et des motifs simples avec *.
• login exécute le flux OAuth pour les serveurs HTTP configurés avec auth: "oauth". La première exécution affiche une URL d’autorisation ; relancez la commande avec --code après l’approbation.
• logout efface les identifiants OAuth enregistrés pour le serveur nommé sans supprimer sa définition enregistrée.
• reload libère les environnements d’exécution MCP en processus mis en cache uniquement pour le processus CLI actuel. Les processus Gateway ou d’agent exécutés dans un autre processus nécessitent toujours leur propre parcours de rechargement ou de redémarrage.
• Utilisez transport: "streamable-http" pour les serveurs MCP HTTP diffusables. openclaw mcp set normalise également la valeur native de la CLI type: "http" vers la même forme de configuration canonique à des fins de compatibilité.
• unset échoue si le serveur nommé n’existe pas.

Exemples :

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

Recettes courantes de serveurs

Ces exemples enregistrent uniquement les définitions des serveurs. Exécutez ensuite openclaw mcp doctor --probe pour prouver que le serveur démarre et expose des outils.

openclaw mcp add files \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-filesystem \  --arg "$HOME/Documents" \  --include 'read_file,list_directory,search_files'openclaw mcp doctor files --probe

openclaw mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

openclaw mcp add docs \  --url https://mcp.example.com/mcp \  --transport streamable-http \  --auth oauth \  --oauth-scope docs.read \  --timeout 20 \  --connect-timeout 5 \  --include 'search,read_*'openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'openclaw mcp doctor cua-driver --probe

Structures de sortie JSON

Utilisez --json pour les scripts et les tableaux de bord. Les ensembles de champs peuvent s'enrichir au fil du temps ; les consommateurs doivent donc ignorer les clés inconnues.

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "Les identifiants OAuth ne sont pas autorisés ; exécutez openclaw mcp login docs"        }      ]    }  ]}

{  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

Exemple de structure de configuration :

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

Transport stdio

Lance un processus enfant local et communique via stdin/stdout.

Transport SSE / HTTP

Se connecte à un serveur MCP distant via les événements envoyés par le serveur HTTP.

Exemple :

{  "mcp": {    "servers": {      "remote-tools": {        "url": "https://mcp.example.com",        "auth": "oauth",        "timeout": 20,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

Les valeurs sensibles dans url (informations utilisateur) et headers sont masquées dans les journaux et la sortie d'état. openclaw mcp doctor avertit lorsque des entrées headers ou env apparemment sensibles contiennent des valeurs littérales, afin que les opérateurs puissent retirer ces valeurs de la configuration validée dans le dépôt.

Flux de travail OAuth

OAuth est destiné aux serveurs MCP HTTP qui annoncent le flux OAuth MCP. Les en-têtes Authorization statiques sont ignorés pour un serveur lorsque auth: "oauth" est activé. Les identifiants enregistrés par openclaw mcp login fonctionnent avec le MCP intégré, les exécuteurs CLI et le serveur d'application Codex local.

Tant que les identifiants ne sont pas disponibles, OpenClaw omet uniquement ce serveur MCP de l'exécution de l'agent au lieu de faire échouer le tour de l'agent. L'opérateur, ou un agent disposant d'un accès au shell, peut alors exécuter openclaw mcp login <name> et utiliser le serveur lors d'un tour ultérieur.

Lorsqu'un service MCP distant s'appuie déjà sur un profil d'authentification OpenClaw distinct capable d'actualiser les identifiants, vous pouvez éventuellement définir oauth.authProfileId. OpenClaw actualise l'une ou l'autre source d'identifiants avant la projection d'exécution et transmet uniquement le jeton d'accès actuel au client MCP en aval.

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Si le fournisseur renouvelle les jetons ou si l'état d'autorisation reste bloqué, exécutez openclaw mcp logout <name>, puis répétez login. logout peut effacer les identifiants d'un serveur HTTP enregistré même après la suppression de auth: "oauth" de la configuration, tant que le nom et l'URL du serveur permettent toujours d'identifier l'entrée du magasin d'identifiants.

Transport HTTP avec diffusion en continu

streamable-http est une option de transport supplémentaire aux côtés de sse et stdio. Elle utilise la diffusion HTTP pour la communication bidirectionnelle avec les serveurs MCP distants.

La configuration OpenClaw utilise transport: "streamable-http" comme orthographe canonique. Les valeurs MCP natives de la CLI type: "http" sont acceptées lorsqu’elles sont enregistrées avec openclaw mcp set et corrigées par openclaw doctor --fix dans une configuration existante, mais transport est la valeur directement utilisée par OpenClaw intégré.

Exemple :

{  "mcp": {    "servers": {      "streaming-tools": {        "url": "https://mcp.example.com/stream",        "transport": "streamable-http",        "connectTimeout": 10,        "timeout": 30,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

Interface de contrôle

L’interface de contrôle dans le navigateur comprend une page dédiée aux paramètres MCP à l’adresse /settings/mcp ; l’ancien chemin /mcp reste un alias. La page affiche le nombre de serveurs configurés, des récapitulatifs des serveurs activés, OAuth et filtrés, des lignes de transport par serveur, des commandes d’activation et de désactivation, des commandes CLI courantes et un éditeur limité à la section de configuration mcp.

Utilisez cette page pour les modifications opérateur et un inventaire rapide. Utilisez openclaw mcp doctor --probe ou openclaw mcp probe lorsque vous avez besoin d’une vérification en direct du serveur.

Procédure opérateur :

1. Ouvrez l’interface de contrôle et choisissez MCP.
2. Consultez les cartes récapitulatives pour connaître le nombre total de serveurs, les serveurs activés, OAuth et filtrés.
3. Utilisez chaque ligne de serveur pour consulter le transport, l’authentification, le filtre, le délai d’expiration et les indications de commande.
4. Basculez l’activation lorsque vous souhaitez conserver une définition tout en l’excluant de la découverte à l’exécution.
5. Modifiez la section de configuration mcp dédiée pour les changements structurels tels que de nouveaux serveurs, des en-têtes, TLS, des métadonnées OAuth ou des filtres d’outils.
6. Choisissez Enregistrer pour uniquement conserver la configuration, ou Enregistrer et publier pour l’appliquer par l’intermédiaire du chemin de configuration du Gateway.
7. Exécutez openclaw mcp doctor --probe lorsque vous avez besoin de vérifier en direct que le serveur modifié démarre et répertorie les outils.

Remarques :

• les extraits de commande placent les noms de serveur entre guillemets afin que les noms inhabituels restent copiables dans un shell
• les valeurs affichées ressemblant à des URL sont masquées avant le rendu lorsqu’elles contiennent des identifiants intégrés
• la page ne démarre pas elle-même les transports MCP
• les environnements d’exécution actifs peuvent nécessiter openclaw mcp reload, la publication de la configuration du Gateway ou un redémarrage du processus, selon le processus qui possède les clients MCP

Applications MCP

OpenClaw peut afficher les outils qui implémentent l’extension MCP Apps stable. Les applications sont facultatives, car leur HTML provient du serveur MCP configuré et peut demander des outils ou des ressources visibles par l’application à ce même serveur.

Activez le pont hôte :

openclaw config set mcp.apps.enabled true --strict-json

Redémarrez le Gateway après avoir modifié ce paramètre. Lorsqu’il est activé, OpenClaw démarre un écouteur HTTP(S) réservé au bac à sable sur le port du Gateway plus un (pour le Gateway par défaut, 18790). L’interface de contrôle charge les applications depuis cette origine distincte ; l’écouteur ne sert jamais l’interface de contrôle, les routes Gateway authentifiées ni les données utilisateur.

Les connexions directes au Gateway doivent avoir accès aux deux ports. Si un proxy inverse ou un terminateur TLS expose l’interface de contrôle, attribuez aux applications une origine publique dédiée et transmettez uniquement cette origine à l’écouteur du bac à sable :

{  mcp: {    apps: {      enabled: true,      sandboxOrigin: "https://mcp-apps.example.com",      sandboxPort: 18790,    },  },}

L’origine du bac à sable doit être différente de celle de l’interface de contrôle. N’y hébergez aucun autre contenu authentifié ou sensible.

Par exemple, la démonstration React basique officielle peut être configurée comme suit :

{  mcp: {    apps: { enabled: true },    servers: {      "basic-react": {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],      },    },  },}

Comportement et limites de sécurité :

• OpenClaw annonce l’extension io.modelcontextprotocol/ui uniquement lorsque les applications sont activées.
• Seules les ressources ui:// avec le type MIME exact text/html;profile=mcp-app sont affichées.
• Les ressources de l’interface utilisateur sont limitées à 2 Mio, placées derrière un proxy à double iframe sur une origine externe dédiée, chargées dans une origine d’application interne opaque et contraintes par une CSP dérivée des métadonnées de la ressource.
• Les outils réservés aux applications (_meta.ui.visibility: ["app"]) restent absents des listes d’outils du modèle. Les applications ne peuvent appeler que les outils qui leur sont visibles sur leur serveur propriétaire.
• Les autorisations d’application liées à l’origine, telles que la caméra, le microphone et la géolocalisation, ne sont pas accordées tant que les documents internes de l’application utilisent des origines opaques pour assurer l’isolation entre les applications.
• Le HTML de l’application, les arguments complets des outils et les résultats bruts résident dans un bail d’affichage en mémoire limité à dix minutes. Ils ne sont ni écrits sur le disque ni copiés dans les métadonnées d’aperçu de la transcription, et une vue expirée ne redémarre pas son environnement d’exécution MCP.
• openclaw security audit émet un avertissement tant que le pont est activé. Désactivez-le avec openclaw config set mcp.apps.enabled false --strict-json lorsqu’il n’est pas nécessaire.

Limites actuelles

Cette page documente le pont tel qu’il est fourni aujourd’hui.

Limites actuelles :

• la découverte des conversations dépend des métadonnées existantes des routes de session du Gateway
• aucun protocole push générique au-delà de l’adaptateur propre à Claude
• aucun outil de modification de message ni de réaction pour le moment
• le transport HTTP/SSE/streamable-http se connecte à un seul serveur distant ; aucun serveur amont multiplexé pour le moment
• permissions_list_open inclut uniquement les approbations observées pendant que le pont est connecté

Pages connexes

• Référence de la CLI
• Plugins