MCP

ZeroClaw est un client MCP : il se connecte à des serveurs Model Context Protocol externes et expose leurs outils à l’agent. Chaque outil MCP est préfixé sous la forme <server>__<tool> (par exemple filesystem__read_file), de sorte que les outils provenant de serveurs différents n’entrent jamais en collision.

Configurer MCP

Le support de MCP est activé par défaut, mais aucun outil MCP externe n’est exposé tant qu’au moins un serveur n’est pas configuré sous mcp.servers et qu’un agent se voit attribuer ce serveur via ses mcp_bundles (voir le filtrage des serveurs par agent ci-dessous). Configurez via le gateway, zerocode, ou zeroclaw config set :

zeroclaw config set mcp.servers.filesystem.command npx

Définissez mcp.enabled = false pour désactiver le chargement des outils MCP sans supprimer les définitions de serveur.

Portée des serveurs par agent (mcp_bundles)

Une entrée [[mcp.servers]] ne définit qu’un serveur. Les serveurs auxquels un agent se connecte effectivement sont déterminés par les agents.<alias>.mcp_bundles de cet agent, et le modèle est sécurisé par défaut : l’omission ne constitue pas une autorisation.

• Un agent sans mcp_bundles ne se connecte à aucun serveur MCP, même lorsque mcp.servers est non vide.
• Un bundle [mcp_bundles.<alias>] désigne les serveurs qu’il accorde par leur name mcp.servers, avec une liste exclude optionnelle. Le grant d’un agent correspond à l’union des serveurs de tous les bundles qu’il référence, soustraite de tout name exclu par l’un de ces bundles (le refus l’emporte).
• Un alias de bundle inconnu, ou un nom de serveur de bundle qui ne correspond à aucun serveur configuré, n’accorde aucun accès. Les deux échouent en mode fermé et sont signalés comme des avertissements non fatals par la validation de la configuration, de sorte qu’une faute de frappe restreint l’accès d’un agent au lieu de l’élargir.

[[mcp.servers]]
name = "filesystem"
command = "npx"

[mcp_bundles.files]
servers = ["filesystem"]

[agents.assistant]
mcp_bundles = ["files"]   # se connecte à `filesystem`; un agent sans cela n'obtient aucun serveur MCP

• Les modifications du bundle deviennent effectives au redémarrage de la session. Le résolveur (Config::mcp_servers_for_agent) s’exécute au moment de la création de la session/agent ; la modification de [mcp_bundles.*] ou de agents.<alias>.mcp_bundles pendant qu’une session est active ne modifie pas les serveurs connectés à cette session. Fermez et redémarrez les sessions concernées pour appliquer les nouvelles autorisations.

Il s’agit de la frontière de connexion (les serveurs auxquels un agent s’adresse). Les contrôles allowed_tools / excluded_tools ci-dessous sont la frontière de capacité par outil appliquée en plus de ce qu’un serveur autorisé expose.

Transports

Un serveur est accessible via l’un des trois transports (le champ transport) :

env (stdio) et headers (http/sse) sont stockés en tant que secrets ; headers contient généralement le jeton Authorization: Bearer … pour le serveur en amont.

Ajoutez un serveur via la passerelle, zerocode, ou zeroclaw config set (par exemple zeroclaw config set mcp.servers.filesystem.command npx). Un serveur stdio nécessite command plus args/env optionnels ; un serveur http/sse nécessite url plus headers optionnels. Les commandes par champ figurent dans le tableau des champs ci-dessous.

Modification des serveurs

Trois interfaces modifient la même table [[mcp.servers]] :

• config.toml : modifiez manuellement les clés documentées ci-dessous. La table complète est rétablie à l’enregistrement.
• zerocode TUI (/config -> mcp.servers) : éditeur dédié à chaque champ. La section affiche une ligne par serveur, identifiée par le name du serveur ; ouvrez une ligne pour modifier transport, command / url, headers, env et tool_timeout_secs en tant que champs individuels. + Add crée une nouvelle entrée initialisée avec le nom que vous fournissez ; la suppression dans la liste des alias retire l’entrée. Le champ name ne se modifie pas en ligne, car renommer la clé naturelle en cours d’édition invaliderait les références en cours ; utilisez le tableau de bord ou modifiez config.toml à la main pour renommer pour le moment.
• Tableau de bord web : affiche actuellement mcp.servers via un éditeur de tableau JSON. Une migration vers la même interface par champ que celle utilisée par la TUI est prévue ; en attendant, le tableau de bord reste un éditeur utilisable, mais plus rudimentaire.

Champs du serveur

Champs par serveur ([[mcp.servers]]), générés à partir du schéma :

zeroclaw config set mcp.servers.args <value>

export ZEROCLAW_mcp__servers__args=

zeroclaw config set mcp.servers.command <value>

export ZEROCLAW_mcp__servers__command=

zeroclaw config set mcp.servers.env    # entrée masquée, stockée chiffrée

export ZEROCLAW_mcp__servers__env=

zeroclaw config set mcp.servers.headers    # entrée masquée, stockée chiffrée

export ZEROCLAW_mcp__servers__headers=

zeroclaw config set mcp.servers.max_response_bytes <value>

export ZEROCLAW_mcp__servers__max_response_bytes=

zeroclaw config set mcp.servers.name <value>

export ZEROCLAW_mcp__servers__name=

zeroclaw config set mcp.servers.pinned_resources <value>

export ZEROCLAW_mcp__servers__pinned_resources=

zeroclaw config set mcp.servers.tls_ca_cert_path <value>

export ZEROCLAW_mcp__servers__tls_ca_cert_path=

zeroclaw config set mcp.servers.tool_timeout_secs <value>

export ZEROCLAW_mcp__servers__tool_timeout_secs=

zeroclaw config set mcp.servers.transport <value>

export ZEROCLAW_mcp__servers__transport=

zeroclaw config set mcp.servers.url <value>

export ZEROCLAW_mcp__servers__url=

tool_timeout_secs est un délai d’expiration optionnel par appel ; il doit être supérieur à 0 et est plafonné à 600 secondes.

Confiance dans une CA personnalisée

Pour un serveur HTTP ou SSE dont le certificat est délivré par une autorité de certification privée, définissez tls_ca_cert_path sur un chemin absolu contenant un ou plusieurs certificats d’autorité de certification encodés au format PEM. Les certificats configurés sont ajoutés au magasin de confiance par défaut ; les vérifications de la chaîne de certificats, de l’expiration et du nom d’hôte restent activées.

Un fichier CA dont le chemin est relatif, qui est manquant, illisible, vide, trop volumineux, non ordinaire ou invalide constitue une erreur de connexion bloquante pour ce serveur. Le chemin doit désigner un fichier ordinaire dont la taille ne dépasse pas 1 MiB. Les liens symboliques sont suivis, de sorte que la rotation des certificats et les configurations de secrets montés qui exposent le bundle via un lien symbolique fonctionnent comme prévu ; le fichier cible est validé après son ouverture, et tout lien symbolique qui pointe vers un répertoire, un périphérique ou un FIFO est rejeté. ZeroClaw ne désactive jamais la vérification et n’effectue jamais de repli silencieux lorsque ce champ est défini. L’URL du serveur configurée et tout point de terminaison de messages annoncé par un serveur SSE doivent utiliser https:// ; les URL en clair et les redirections vers un protocole moins sécurisé sont rejetées avant l’envoi des en-têtes de requête ou du contenu. La valeur est prise en compte au démarrage de la session MCP ; redémarrez la session concernée après l’avoir modifiée. Supprimez le champ et redémarrez la session pour revenir au magasin de confiance par défaut. Les serveurs Stdio l’ignorent.

Champs de premier niveau

zeroclaw config set mcp.deferred_loading <value>

export ZEROCLAW_mcp__deferred_loading=

zeroclaw config set mcp.servers <value>

export ZEROCLAW_mcp__servers=

Chargement différé

mcp.deferred_loading est défini sur false par défaut, de sorte que les outils MCP configurés sont inclus de manière anticipée dans le contexte du modèle. Définissez-le sur true pour placer uniquement les noms des outils MCP dans l’invite système ; le LLM appelle l’outil intégré tool_search pour récupérer le schéma complet d’un outil avant de l’invoquer. Cela permet de garder une petite fenêtre de contexte initiale lorsqu’un serveur expose de nombreux outils.

Sécurité et approbation

Les appels d’outils MCP passent par la même barrière d’approbation que tous les autres outils, régie par le profil de risque de l’agent (risk_profiles.<alias>). L’étape de découverte tool_search est approuvée automatiquement afin que le chargement différé de MCP puisse fonctionner dans les sessions non interactives, mais les outils découverts depuis les serveurs MCP suivent toujours la politique d’approbation normale :

• Au niveau d’autonomie level = full, aucune confirmation d’appel d’outil (outils MCP inclus).
• Sinon, un appel d’outil MCP demande une approbation, sauf si son nom préfixé (<server>__<tool>) figure dans la liste auto_approve du profil. auto_approve = ["*"] approuve tout ; une entrée exacte comme auto_approve = ["filesystem__read_file"] approuve uniquement cet outil.
• always_ask est l’inverse : un nom (ou "*") à cet endroit déclenche toujours une demande de confirmation, ce qui prévaut sur auto_approve.

Autorisation : allowed_tools / excluded_tools

Les portes d’approbation déterminent quand un appel d’outil nécessite une validation humaine. Les portes d’autorisation déterminent si l’agent peut appeler un outil tout court. Les deux sont indépendantes.

Conservez les trois contrôles d’outils MCP sur leurs propres axes :

Pour les outils MCP découverts au moment de l’exécution, le contrat de capacité comporte une exception spécifique à MCP :

• Si le champ allowed_tools du profil de risque est vide ou omis, aucune contrainte d’autorisation ne s’applique ; chaque outil découvert (MCP ou intégré) est accessible. La configuration TOML ne fait pas de distinction entre un champ omis et allowed_tools = [] ; les deux se désérialisent vers le même état « aucune contrainte d’autorisation » au niveau du profil de risque. Si vous avez besoin d’une barrière explicite de refus total, faites-le sur la liste allowed_tools par exécution fournie par l’appelant (les tâches cron et autres restricteurs transmettent cette liste directement) ou via excluded_tools couvrant les outils spécifiques que vous souhaitez bloquer.
• Si allowed_tools n’est pas vide, tout outil MCP dont le nom contient __ (la convention <server>__<tool>) est automatiquement ajouté à la liste blanche effective sans devoir y être répertorié individuellement. Les outils intégrés non-MCP nécessitent toujours une entrée exacte.
• excluded_tools opère toujours par soustraction, y compris à partir de l’ensemble MCP auto-admis. Pour bloquer un seul outil MCP comme filesystem__write_file tout en gardant le reste du serveur filesystem accessible, placez-le dans excluded_tools.

La justification : avant cette exception, chaque agent qui épinglait une liste allowed_tools pour verrouiller sa surface intégrée perdait silencieusement tous les outils MCP, même ceux explicitement configurés par l’opérateur. Le coût est que la liste de refus est désormais le principal levier de l’opérateur pour bloquer les capacités MCP destructrices sous un profil épinglé par liste d’autorisation.

Si vous souhaitez le modèle strict d’avant cette modification, où vous n’autorisez que les outils MCP que vous listez explicitement sans auto-autorisation __, combinez une entrée allowed_tools explicite avec une entrée excluded_tools pour chaque outil voisin destructeur que vous devez bloquer :

[risk_profiles.assistant]
allowed_tools = [
  "file_read",
  "filesystem__read_file",
]
# Bloque l'équivalent destructeur qui serait sinon automatiquement admis via
# l'exception `__` ci-dessus.
excluded_tools = [
  "filesystem__write_file",
]
auto_approve = [
  "filesystem__read_file",
]

L’exception d’admission automatique MCP __ se limite uniquement au champ allowed_tools du profil de risque. Les listes d’autorisation par exécution fournies par l’appelant, comme un allowed_tools de tâche cron ou toute autre invocation restreinte qui transmet une liste explicite au runtime, sont toujours traitées comme des intersections strictes de listes explicites, sans admission automatique __ par-dessus. Une tâche cron qui se restreint à allowed_tools = ["cron_add"] n’exposera pas filesystem__write_file au modèle, même si le profil de risque de l’agent l’admettrait automatiquement via la convention __ ; la restriction par exécution demeure une frontière de capacités fiable, quel que soit le nombre de serveurs MCP configurés.

auto_approve seul ne masque pas un outil au modèle ; il répond uniquement à la question d’approbation après que le modèle a sélectionné cet outil. Utilisez tool_filter_groups pour réduire le bruit du prompt et allowed_tools / excluded_tools pour imposer une limite de capacités.

Consultez Niveaux d’autonomie pour la surface complète des champs par profil, et la Référence de configuration pour chaque champ MCP et sa valeur par défaut.

MCP Ressources et invites

Outre les outils MCP, ZeroClaw expose les ressources et les invites des serveurs connectés.

Outils

Deux outils intégrés sont disponibles (sous réserve de la politique d’accès aux outils de votre agent) :

• mcp_resources: action: "list" (server, cursor optionnels) liste les ressources ; action: "read" avec uri (préfixé <server>__<uri>) renvoie le contenu.
• mcp_prompts : action: "list" liste les prompts ; action: "get" avec name (préfixé <server>__<name>) et arguments optionnels renvoie les messages de prompt rendus.

Les serveurs qui n’annoncent pas les capacités resource/prompt sont ignorés, et les appels contre eux renvoient une erreur claire « does not support ».

Épinglage des ressources dans le contexte

Chaque entrée de serveur MCP accepte un champ optionnel pinned_resources : une liste d’URI de ressources à lire une fois au démarrage et à injecter dans le prompt système. Configurez-le via les mêmes interfaces de configuration utilisées pour définir le serveur (la gateway, zerocode ou zeroclaw config set, comme indiqué sous Configurer MCP), en spécifiant les ressources que vous souhaitez que l’agent conserve en permanence. Le champ est vide par défaut, les serveurs ne l’utilisant pas ne sont donc pas affectés.

Le contenu épinglé est lu une fois par exécution (pas de rafraîchissement en direct) et est étiqueté trust="untrusted-external" afin que le modèle le traite comme des données, et non comme des instructions.

Blobs de ressources intégrés dans les résultats des outils

Lorsqu’un résultat MCP tools/call inclut un élément de contenu de la forme type: "resource" avec un blob imbriqué (base64), ZeroClaw ne déverse pas ce base64 dans le contexte du modèle. À la place, il matérialise les octets dans le répertoire uploads/ de l’espace de travail de la session (avec le même utilitaire partagé et la même limite de 10 MB que pour les resource.blob entrants via ACP), puis remplace la sortie de l’outil destinée au modèle par un texte de provenance sans blob, accompagné d’un marqueur [Document: …] ou [IMAGE:…]. Ce comportement dépend de la forme du contenu, et non du nom de l’outil. La matérialisation n’envoie pas automatiquement le fichier aux clients ACP ; l’agent appelle toujours deliver_file lorsqu’un envoi sortant est nécessaire. Voir réception du blob session/prompt par ACP.

Comme le résultat provient d’un serveur non approuvé, deux limites par appel sont appliquées avant le décodage, le hachage ou l’écriture de tout blob : au maximum 64 blobs de ressources par résultat de tools/call, et une taille décodée cumulée estimée d’au plus 10 MiB pour l’ensemble. Lorsqu’un résultat dépasse l’une ou l’autre de ces limites, chaque blob de ressource est remplacé par un marqueur [attachment unavailable: …] et rien n’est écrit sur le disque, de sorte qu’un tableau contenant de nombreux blobs vides ou minuscules ne peut pas imposer un traitement par élément. Chaque blob individuel reste soumis à la même limite de 10 MB par fichier.

Indépendamment de ces budgets décodés, chaque serveur MCP HTTP/SSE dispose également d’une limite de taille du corps de réponse au niveau du transport, max_response_bytes, appliquée aux octets bruts encodés transmis sur le réseau avant l’analyse du corps, afin qu’un serveur ne puisse pas imposer une lecture illimitée. Il ne s’agit pas de la limite décodée de 10 MiB mentionnée ci-dessus : sa valeur par défaut est de 16 078 168 octets, soit l’expansion en base64 de l’agrégat décodé de 10 MiB, plus une marge pour l’enveloppe JSON-RPC, afin qu’un blob valide proche de la limite soit tout de même matérialisé. Définissez max_response_bytes sur un serveur pour remplacer cette valeur ; le définir à 0 ou ne pas le définir utilise cette valeur par défaut.

Sécurité

Le contenu des ressources et des prompts provient du serveur MCP configuré et est traité comme non fiable : il est enveloppé de provenance, expurgé des secrets et borné en longueur avant d’entrer dans le contexte. L’accès à mcp_resources / mcp_prompts et aux serveurs spécifiques est régi par la politique d’accès aux outils de votre agent (profil de risque), et se restreint correctement lors de la délégation à des sous-agents.