Laissez votre agent de programmation utiliser le navigateur où vous êtes déjà connecté.

Qui démarre quoi

Votre client MCP lance le paquet npm comme processus enfant local via stdio. Ce processus n'écoute que sur 127.0.0.1:17374. L'extension se connecte à lui, puis exécute chaque tâche via la boucle agent de WebBrain dans l'onglet du navigateur sélectionné.

Le serveur n'est pas un second navigateur et ne copie pas les cookies. C'est un point de transfert local entre le client MCP et l'extension. Le profil du navigateur — et donc la session authentifiée — ne bouge jamais.

Avant de vous connecter

Enregistrez le serveur auprès de votre client MCP

Utilisez l'une des configurations spécifiques au client ci-dessous, une seule fois. Ce sont des commandes d'installation, pas la façon dont vous demandez des tâches au navigateur. Après l'enregistrement, le client démarre le serveur pour vous et vous continuez à discuter normalement ; ne lancez pas de copie manuelle en parallèle sur le même port.

Application Codex, CLI ou extension IDE

codex mcp add webbrain -- npx -y @webbrain/mcp-server

Codex stocke les serveurs MCP dans ~/.codex/config.toml ; l'application, le CLI et l'extension IDE sur le même hôte Codex partagent cette configuration. Pour les tâches de navigateur longues, ouvrez ce fichier et accordez à l'outil plus de temps que le budget par défaut de Codex par appel :

[mcp_servers.webbrain]
command = "npx"
args = ["-y", "@webbrain/mcp-server"]
tool_timeout_sec = 360

Redémarrez l'application ou l'extension IDE après modification du fichier. Dans le CLI, exécutez codex mcp list pour confirmer l'entrée, et utilisez /mcp dans une session Codex pour inspecter le serveur connecté. Consultez le guide officiel MCP de Codex pour la configuration hôte partagée et toutes les options prises en charge.

Claude Code

claude mcp add --transport stdio webbrain -- npx -y @webbrain/mcp-server

Le transport explicite correspond à la configuration MCP actuelle de Claude Code. Une fois ajouté, exécutez claude mcp list pour vérifier l'état du serveur.

Cursor

Ajoutez un serveur stdio local dans les réglages MCP de Cursor, ou placez ce contenu dans le fichier JSON MCP utilisé par Cursor. Le format suit le format des serveurs MCP locaux de Cursor :

{
  "mcpServers": {
    "webbrain": {
      "command": "npx",
      "args": ["-y", "@webbrain/mcp-server"]
    }
  }
}

OpenCode

Ajoutez cette entrée au fichier ~/.config/opencode/opencode.json, en utilisant le format des serveurs MCP locaux d'OpenCode :

{
  "mcp": {
    "webbrain": {
      "type": "local",
      "command": ["npx", "-y", "@webbrain/mcp-server"]
    }
  }
}

OpenClaw

Enregistrez WebBrain dans OpenClaw comme serveur MCP sortant. N'utilisez pas openclaw mcp serve pour cette intégration : cette commande fait d'OpenClaw lui-même un serveur, dans le sens inverse.

openclaw mcp add webbrain \
  --command npx \
  --arg -y \
  --arg @webbrain/mcp-server \
  --timeout 360

mcp add sonde le serveur stdio avant de l'enregistrer. Exécutez openclaw mcp status --verbose pour inspecter la définition enregistrée. Les profils d'outils normaux coding et messaging incluent les serveurs MCP configurés ; le profil minimal, un refus explicite bundle-mcp ou une politique d'outils en sandbox peut les masquer. Consultez le guide MCP d'OpenClaw pour l'état actuel du registre et des politiques.

Exécution manuelle

Le démarrage manuel est utile pour diagnostiquer l'écouteur, mais il n'est pas nécessaire lors d'une utilisation normale de MCP :

npx -y @webbrain/mcp-server

Laissez ce terminal ouvert. Le fermer arrête l'écouteur du pont. Depuis une copie du code source, exécutez npm install, npm run build, puis npm start dans mcp-server/.

Dirigez WebBrain vers l'écouteur local

1. Démarrez ou redémarrez votre client MCP. Son serveur WebBrain doit tourner avant que l'extension puisse se connecter.
2. Ouvrez les réglages de WebBrain. Allez dans Réglages → Bridge.
3. Définissez l'URL exacte. Saisissez ws://127.0.0.1:17374/extension.
4. Collez la clé d'appairage. Exécutez npx -y @webbrain/mcp-server pairing-key dans un terminal (ou ouvrez ~/.webbrain/bridge-key) et collez la clé dans le champ Clé d'appairage. Le serveur ne fait confiance qu'au navigateur qui prouve détenir cette clé. Si le champ est absent, mettez d'abord WebBrain à jour.
5. Activez le pont cloud. L'état doit passer de « connexion en cours » à « connecté ». Le nom est dû à des raisons historiques : cette cible est locale.
6. Vérifiez la connexion de bout en bout. Demandez au client MCP d'appeler webbrain_connection. « Connected » prouve que le client, le serveur local, l'écouteur WebSocket et la poignée de main de l'extension sont tous prêts.

Décrivez la tâche du navigateur en langage naturel

Dans Codex, Claude Code, Cursor, OpenClaw ou OpenCode, écrivez la demande comme vous la donneriez à un collègue. Mentionner WebBrain rend votre intention sans ambiguïté ; incluez la page, le résultat attendu, la portée et si des modifications sont autorisées.

Lire sans changer la page

Utilisez WebBrain pour lire le tableau de bord Stripe déjà ouvert dans mon navigateur. Listez les paiements échoués des sept derniers jours avec client, montant, devise, date et motif d'échec. Ne changez rien.

Renvoyer un JSON prévisible

Utilisez WebBrain pour extraire toutes les factures en retard du tableau de bord ouvert dans mon navigateur. Renvoyez un JSON avec client, montant, devise, échéance et URL de la facture. Ne changez rien.

Interagir avec la page

Utilisez le mode Act de WebBrain pour ouvrir la fiche client déjà affichée dans mon navigateur et mettre à jour le nom de l'entreprise en Acme Europe. Arrêtez-vous avant toute soumission ou confirmation finale.

L'agent de programmation choisit webbrain_run pour la lecture ou l'interaction générales et webbrain_extract lorsque des données structurées sont demandées. Il fournit les arguments, surveille l'exécution et présente le résultat de WebBrain dans la conversation. Le mode Ask peut lire et extraire ; il ne peut ni cliquer, ni saisir, ni naviguer, ni soumettre. Le mode Act peut interagir, soumis aux autorisations habituelles de WebBrain côté navigateur.

webbrain_run(
  task: "read the open Stripe dashboard and list failed payments from the last 7 days with customer, amount, currency, date, and failure reason",
  mode: "ask"
)

Pour une tâche qui doit interagir, dites explicitement « utilisez le mode Act de WebBrain » et gardez le navigateur visible. WebBrain appliquera ses demandes d'approbation habituelles, par capacité et par origine.

Les outils que votre client MCP utilise pour vous

Vous choisissez normalement un résultat, pas un outil. Votre client MCP lit ces descriptions, sélectionne l'outil approprié, remplit ses entrées à partir de votre demande et gère les appels suivants. Cette référence vous aide à comprendre ou déboguer ce comportement.

Demandez du JSON structuré

En usage normal, dites ce qu'il faut extraire et nommez les champs souhaités : « extrayez toutes les factures en retard du tableau de bord ouvert avec WebBrain, en renvoyant un JSON avec client, montant, devise, échéance et URL de la facture. » Un client MCP compétent peut traduire ces champs en schéma requis et appeler webbrain_extract pour vous.

L'exemple sous forme de fonction ci-dessous montre l'appel d'outil équivalent pour les développeurs de clients et le débogage. Décrivez la logique de sélection dans task ; ne décrivez la forme de sortie que dans output_schema.

webbrain_extract(
  task: "extract every overdue invoice visible in this account; preserve the displayed currency and use ISO dates where the page provides a full date",
  output_schema: {
    type: "object",
    properties: {
      invoices: {
        type: "array",
        items: {
          type: "object",
          properties: {
            customer: { type: "string" },
            amount: { type: "number" },
            currency: { type: "string" },
            due_date: { type: "string" },
            invoice_url: { type: "string" }
          },
          required: ["customer", "amount", "currency", "due_date"]
        }
      }
    },
    required: ["invoices"]
  }
)

• Utilisez une racine objet avec des champs properties et required explicites.
• Demandez les données les plus étroites dont vous avez besoin. Un schéma n'accorde pas l'accès à des données invisibles pour la session du navigateur.
• L'outil est en lecture seule, mais le texte de la page et le résultat sont tout de même envoyés au fournisseur LLM configuré dans WebBrain.
• Si le résultat est trop volumineux pour l'instantané persistant de l'exécution, le statut peut indiquer que le résultat stocké a été tronqué. Réduisez la demande et réessayez.

Comprendre le cycle de vie d'une exécution

La plupart des clients MCP gèrent ce cycle de vie pour vous : ils attendent le résultat, affichent la question de clarification de WebBrain lorsqu'une intervention humaine est nécessaire, et poursuivent avec votre réponse. Les appels explicites ci-dessous sont utiles pour les développeurs de clients, le dépannage ou pour demander volontairement au client de démarrer une longue tâche en arrière-plan.

Un appel au premier plan attend par défaut. Pour un travail long, le client peut définir wait: false et interroger avec webbrain_status.

# Référence au niveau des outils
# Démarrer sans attendre
webbrain_run(task: "compare the invoices across all visible pages", mode: "ask", wait: false)

# Interroger l'ID renvoyé
webbrain_status(run_id: "mcp_…")

Un dépassement de délai d'une exécution WebBrain rend la main au client MCP, mais n'interrompt délibérément pas la tâche du navigateur. Interrogez le run_id renvoyé. Cela évite qu'un dépassement de délai ne tue silencieusement une tâche qui a peut-être déjà effectué une action décisive.

Lorsque WebBrain pose une question

L'instantané en pause contient une question lisible par un humain et un clarify_id. Affichez cette question à l'utilisateur. Envoyez sa réponse mot pour mot ; ne déduisez rien.

webbrain_respond(
  run_id: "mcp_…",
  clarify_id: "clarify_…",
  answer: "Use the Acme EU account."
)

Choisissez la plus petite autorité

L'approbation du client MCP et celle de WebBrain sont des couches indépendantes. Votre client peut demander avant d'appeler webbrain_run ; WebBrain peut demander avant une action importante sur une origine. Une approbation ne remplace pas l'autre.

Les frontières de sécurité à respecter

• Gardez l'écouteur local. Il est lié à 127.0.0.1. Ne transférez pas le port 17374, ne le publiez pas via un pont de conteneurs et ne le mandatez pas sur le réseau.
• Protégez la clé d'appairage. La boucle locale seule n'est pas une authentification : le serveur ne fait confiance à une socket qu'après qu'elle a répondu à un défi à usage unique par un HMAC clés avec la clé d'appairage ; la clé elle-même ne transite jamais par la socket. Quiconque peut lire ~/.webbrain/bridge-key peut s'appairer, ne collez donc pas la clé dans un chat. L'extension n'authentifie pas le serveur ; considérez donc le code local et les paquets MCP comme des logiciels de confiance.
• Privilégiez Ask. Le travail en lecture seule est plus facile à vérifier et a une portée de dégâts plus limitée.
• Gardez le navigateur visible en mode Act. Vous pouvez arrêter l'exécution dans le panneau latéral, et une navigation ou une saisie inattendue doit être considérée comme une raison d'arrêter.
• Gardez la frontière du fournisseur en tête. Le pont MCP reste local, mais le contenu de la page est envoyé au fournisseur de modèles configuré dans WebBrain. Utilisez un modèle local lorsque le contenu doit rester sur l'appareil.
• Ne confondez pas un délai dépassé avec une restauration en arrière. Abandonner arrête les étapes futures ; cela ne peut pas annuler un e-mail envoyé, un formulaire soumis, un achat ou une autre action déjà menée à bien.

Pour la conception complète, consultez le modèle de sécurité, le document sur la confidentialité et les flux de données et le guide des modes, de la sécurité et de la confidentialité.

Dépannage par symptôme

Configuration de l'environnement

Pour un client stdio, définissez les variables d'environnement dans la configuration MCP de ce client. Si vous changez le port ou le chemin, mettez l'URL du pont cloud dans les réglages de WebBrain à jour pour qu'elle corresponde exactement.

Vous utilisez LM Studio ?

LM Studio utilise le plugin WebBrain Web Tools distinct, et non ce paquet MCP. Ses outils fetch_url et research_url peuvent lire des pages publiques sans l'extension de navigateur ; ses outils de navigateur peuvent déléguer un objectif à votre session Chromium connectée via le port 17375.

Ce que ce serveur ne fait délibérément pas

• Il ne lance pas de navigateur sans interface et ne crée pas de nouveau profil de navigateur.
• Il ne fonctionne pas via la version Firefox.
• Il n'exporte pas les cookies, les identifiants ou le stockage de session.
• Il n'expose pas directement au client MCP les quelque cinquante primitives WebBrain de clic, de saisie, d'iframe, de capture d'écran, de réseau et de DOM.
• Il ne rend pas le pont sûr à exposer à distance.
• Il n'élimine pas le besoin de configurer un modèle dans WebBrain.

Si vous avez besoin d'une automatisation de navigateur déterministe de bas niveau dans un profil isolé, un serveur MCP de type Playwright conviendra peut-être mieux. Utilisez WebBrain MCP quand l'exigence décisive est votre session navigateur connectée existante plus le modèle de sécurité de WebBrain dans le navigateur.