Deja que tu agente de programación use el navegador en el que ya has iniciado sesión.

Qué se inicia dónde

Tu cliente MCP inicia el paquete npm como un proceso hijo local mediante stdio. Ese proceso solo escucha en 127.0.0.1:17374. La extensión se conecta a él y luego ejecuta cada tarea a través del bucle de agente de WebBrain en la pestaña del navegador seleccionada.

El servidor no es un segundo navegador ni copia las cookies. Es un punto de traspaso local entre el cliente MCP y la extensión. El perfil del navegador —y por tanto la sesión autenticada— nunca se mueve.

Antes de conectar

Registra el servidor en tu cliente MCP

Usa una de las configuraciones específicas de cliente siguientes, solo una vez. Son comandos de instalación, no la forma en que solicitas tareas del navegador. Tras registrarlo, el cliente inicia el servidor por ti y sigues chateando con normalidad; no ejecutes una copia manual simultánea en el mismo puerto.

Aplicación de Codex, CLI o extensión para IDE

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

Codex guarda los servidores MCP en ~/.codex/config.toml; la aplicación, la CLI y la extensión para IDE en el mismo host de Codex comparten esa configuración. Para tareas de navegador prolongadas, abre ese archivo y da a la herramienta más tiempo del presupuesto por defecto de Codex por llamada:

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

Reinicia la aplicación o la extensión para IDE tras cambiar el archivo. En la CLI, ejecuta codex mcp list para confirmar la entrada y usa /mcp en una sesión de Codex para inspeccionar el servidor conectado. Consulta la guía oficial de MCP de Codex para ver la configuración de host compartido y todas las opciones admitidas.

Claude Code

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

El transporte explícito coincide con la configuración MCP actual de Claude Code. Después de añadirlo, ejecuta claude mcp list para comprobar el estado del servidor.

Cursor

Añade un servidor stdio local en la configuración MCP de Cursor, o coloca este contenido en el archivo JSON MCP que usa Cursor. El formato sigue el formato de servidores MCP locales de Cursor:

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

OpenCode

Añade esta entrada al archivo ~/.config/opencode/opencode.json, usando el formato de servidores MCP locales de OpenCode:

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

OpenClaw

Registra WebBrain en OpenClaw como servidor MCP saliente. No uses openclaw mcp serve para esta integración: ese comando hace que OpenClaw actúe como servidor, en dirección contraria.

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

mcp add sondea el servidor stdio antes de guardarlo. Ejecuta openclaw mcp status --verbose para inspeccionar la definición guardada. Los perfiles de herramientas normales coding y messaging incluyen los servidores MCP configurados; el perfil minimal, un rechazo explícito de bundle-mcp o una política de herramientas en sandbox pueden ocultarlos. Consulta la guía MCP de OpenClaw para ver el estado del registro y las políticas.

Ejecución manual

Iniciar manualmente es útil para diagnosticar el listener, pero no es necesario en el uso normal de MCP:

npx -y @webbrain/mcp-server

Deja esa terminal abierta. Cerrarla detiene el listener del puente. Desde una copia del código fuente, ejecuta npm install, npm run build y luego npm start dentro de mcp-server/.

Apunta WebBrain al listener local

1. Inicia o reinicia tu cliente MCP. Su servidor WebBrain debe estar en ejecución antes de que la extensión pueda conectar.
2. Abre la configuración de WebBrain. Ve a Configuración → Bridge.
3. Establece la URL exacta. Introduce ws://127.0.0.1:17374/extension.
4. Pega la clave de emparejamiento. Ejecuta npx -y @webbrain/mcp-server pairing-key en una terminal (o abre ~/.webbrain/bridge-key) y pega la clave en el campo Clave de emparejamiento. El servidor solo confía en un navegador que demuestre tener esa clave. Si falta el campo, actualiza WebBrain primero.
5. Activa el puente cloud. El estado debe pasar de «conectando» a «conectado». El nombre es por razones históricas: este destino es local.
6. Verifica la conexión de extremo a extremo. Pide a tu cliente MCP que llame a webbrain_connection. «Connected» demuestra que el cliente, el servidor local, el listener WebSocket y el handshake de la extensión están listos.

Describe la tarea del navegador en lenguaje natural

En Codex, Claude Code, Cursor, OpenClaw u OpenCode, escribe la solicitud como si se la dieras a un compañero de trabajo. Mencionar WebBrain deja tu intención inequívoca; incluye la página, el resultado esperado, el alcance y si se permiten cambios.

Leer sin cambiar la página

Usa WebBrain para leer el panel de Stripe ya abierto en mi navegador. Lista los pagos fallidos de los últimos siete días con cliente, importe, moneda, fecha y motivo del fallo. No cambies nada.

Devolver JSON predecible

Usa WebBrain para extraer todas las facturas vencidas del panel abierto en mi navegador. Devuelve JSON con cliente, importe, moneda, fecha de vencimiento y URL de la factura. No cambies nada.

Interactuar con la página

Usa el modo Act de WebBrain para abrir el registro de cliente ya visible en mi navegador y actualiza el nombre de la empresa a Acme Europe. Detente antes de cualquier envío o confirmación final.

El agente de programación elige webbrain_run para lectura o interacción generales y webbrain_extract cuando se piden datos estructurados. Suministra los argumentos, supervisa la ejecución y presenta el resultado de WebBrain de vuelta en la conversación. El modo Ask puede leer y extraer; no puede hacer clic, escribir, navegar ni enviar. El modo Act puede interactuar, sujeto a los permisos normales de WebBrain en el navegador.

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"
)

Para una tarea que deba interactuar, di explícitamente «usa el modo Act de WebBrain» y mantén el navegador visible. WebBrain aplicará sus solicitudes normales de aprobación por capacidad y por origen.

Las herramientas que tu cliente MCP usa por ti

Normalmente eliges un resultado, no una herramienta. Tu cliente MCP lee estas descripciones, elige la herramienta adecuada, rellena sus entradas según tu solicitud y gestiona las llamadas posteriores. Esta referencia sirve para entender o depurar ese comportamiento.

Solicitar JSON estructurado

En el uso normal, di qué extraer y nombra los campos deseados: «extrae todas las facturas vencidas del panel abierto con WebBrain y devuelve JSON con cliente, importe, moneda, fecha de vencimiento y URL de la factura». Un cliente MCP capaz puede traducir esos campos al esquema requerido y llamar a webbrain_extract por ti.

El ejemplo en forma de función de abajo muestra la llamada de herramienta equivalente para desarrolladores de clientes y depuración. Describe la lógica de selección en task; describe solo la forma de la salida en 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"]
  }
)

• Usa una raíz de objeto con campos properties y required explícitos.
• Pide los datos más estrechos que necesites. Un esquema no otorga acceso a datos que la sesión del navegador no ve.
• La herramienta es de solo lectura, pero el texto de la página y el resultado se envían igualmente al proveedor de LLM configurado en WebBrain.
• Si el resultado es demasiado grande para la instantánea persistente de la ejecución, el estado puede informar de que el resultado almacenado se truncó. Reduce la solicitud y reinténtalo.

Entiende el ciclo de vida de la ejecución

La mayoría de los clientes MCP gestionan este ciclo de vida por ti: esperan el resultado, muestran la pregunta de aclaración de WebBrain cuando se necesita una intervención humana y continúan con tu respuesta. Las llamadas explícitas de abajo son útiles para desarrolladores de clientes, para resolver problemas o para pedir deliberadamente al cliente que inicie tareas largas en segundo plano.

Las llamadas en primer plano esperan por defecto. Para trabajos largos, el cliente puede establecer wait: false y sondear con webbrain_status.

# Referencia a nivel de herramienta
# Iniciar sin esperar
webbrain_run(task: "compare the invoices across all visible pages", mode: "ask", wait: false)

# Sondear el ID devuelto
webbrain_status(run_id: "mcp_…")

Un tiempo de espera agotado de una ejecución de WebBrain devuelve el control al cliente MCP, pero deliberadamente no aborta la tarea del navegador. Sondea el run_id devuelto. Esto evita que un tiempo de espera mate silenciosamente una tarea que quizá ya haya realizado una acción trascendental.

Cuando WebBrain pregunta

La instantánea pausada contiene una pregunta legible por humanos y un clarify_id. Muestra esa pregunta al usuario. Envía su respuesta literalmente; no la infieras.

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

Elige la autoridad mínima

La aprobación del cliente MCP y la de WebBrain son capas independientes. Tu cliente puede preguntar antes de llamar a webbrain_run; WebBrain puede preguntar antes de una acción trascendental en un origen. Una aprobación no sustituye a la otra.

Los límites de seguridad que debes mantener

• Mantén el listener local. Está vinculado a 127.0.0.1. No reenvíes el puerto 17374, no lo publiques a través de un puente de contenedores ni lo proxifies a una red.
• Custodia la clave de emparejamiento. El loopback por sí solo no es autenticación: el servidor solo confía en un socket después de que este responda a un desafío de un solo uso con un HMAC firmado con la clave de emparejamiento; la clave en sí nunca viaja por el socket. Cualquiera que pueda leer ~/.webbrain/bridge-key puede emparejar, así que no pegues la clave en un chat. La extensión no autentica al servidor, así que sigue tratando el código local y los paquetes MCP como software de confianza.
• Usa Ask primero. El trabajo de solo lectura es más fácil de verificar y tiene un radio de impacto menor.
• Mantén el navegador visible en el modo Act. Puedes detener la ejecución en el panel lateral, y una navegación o escritura inesperada debe considerarse una razón para detenerse.
• Recuerda el límite del proveedor. El puente MCP permanece local, pero el contenido de la página se envía al proveedor de modelos configurado en WebBrain. Usa un modelo local cuando el contenido deba permanecer en el dispositivo.
• No confundas un tiempo de espera agotado con una reversión. Abortar detiene los pasos futuros; no puede deshacer un correo enviado, un formulario enviado, una compra u otra acción completada.

Para el diseño completo, consulta el modelo de seguridad, el flujo de privacidad y datos y la guía de modos, seguridad y privacidad.

Solución de problemas por síntoma

Configuración del entorno

Para un cliente stdio, establece las variables de entorno en la configuración MCP de ese cliente. Si cambias el puerto o la ruta, actualiza la URL del puente cloud en la configuración de WebBrain para que coincida exactamente.

¿Usas LM Studio?

LM Studio usa el complemento WebBrain Web Tools aparte, no este paquete MCP. Sus herramientas fetch_url y research_url pueden leer páginas públicas sin la extensión del navegador; sus herramientas de navegador pueden delegar un objetivo a tu sesión de Chromium con sesión iniciada a través del puerto 17375.

Lo que este servidor deliberadamente no hace

• No inicia un navegador sin interfaz ni crea un perfil de navegador nuevo.
• No funciona a través de la versión de Firefox.
• No exporta cookies, credenciales ni almacenamiento de sesión.
• No expone directamente al cliente MCP las unas cincuenta primitivas de clic, escritura, marco, captura de pantalla, red y DOM de WebBrain.
• No hace que el puente sea seguro para exponerlo de forma remota.
• No elimina la necesidad de tener un modelo configurado dentro de WebBrain.

Si necesitas automatización de navegador determinista de bajo nivel en un perfil aislado, un servidor MCP al estilo de Playwright puede encajar mejor. Usa WebBrain MCP cuando el requisito decisivo es tu sesión iniciada existente en el navegador más el modelo de seguridad de WebBrain dentro del navegador.