MCP

openclaw mcp tiene dos funciones:

• ejecutar OpenClaw como servidor MCP con openclaw mcp serve
• gestionar las definiciones de servidores MCP salientes administradas por OpenClaw con list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload y unset

serve corresponde a OpenClaw actuando como servidor MCP. Los demás subcomandos corresponden a OpenClaw actuando como registro del lado del cliente MCP para servidores que sus propios entornos de ejecución podrán consumir más adelante.

Use openclaw acp cuando OpenClaw deba alojar una sesión de entorno de programación y enrutar ese entorno de ejecución mediante ACP.

Elegir la ruta MCP adecuada

OpenClaw como servidor MCP

Esta es la ruta openclaw mcp serve.

Cuándo usar serve

Use openclaw mcp serve cuando:

• Codex, Claude Code u otro cliente MCP deba comunicarse directamente con conversaciones de canales respaldadas por OpenClaw
• ya se disponga de un Gateway de OpenClaw local o remoto con sesiones enrutadas
• se desee un único servidor MCP que funcione con los distintos backends de canales de OpenClaw, en lugar de ejecutar puentes separados para cada canal

Use openclaw acp en su lugar cuando OpenClaw deba alojar el propio entorno de ejecución de programación y mantener la sesión del agente dentro de OpenClaw.

Funcionamiento

openclaw mcp serve inicia un servidor MCP mediante stdio. El cliente MCP es propietario de ese proceso. Mientras el cliente mantenga abierta la sesión stdio, el puente se conecta mediante WebSocket a un Gateway de OpenClaw local o remoto y expone las conversaciones de canales enrutadas mediante MCP.

Elegir un modo de cliente

Qué expone serve

El puente utiliza los metadatos de rutas de sesión existentes del Gateway para exponer conversaciones respaldadas por canales. Una conversación aparece cuando OpenClaw ya tiene un estado de sesión con una ruta conocida, como:

• channel
• metadatos del destinatario o destino
• accountId opcional
• threadId opcional

Esto ofrece a los clientes MCP un único lugar para:

• enumerar las conversaciones enrutadas recientes
• leer el historial de transcripciones reciente
• esperar nuevos eventos entrantes
• enviar una respuesta mediante la misma ruta
• ver las solicitudes de aprobación que lleguen mientras el puente esté conectado

Uso

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

Herramientas del puente

Modelo de eventos

El puente mantiene una cola de eventos en memoria mientras está conectado.

Tipos de eventos actuales:

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

Notificaciones del canal de Claude

El puente también puede exponer notificaciones específicas del canal de Claude. Este es el equivalente en OpenClaw de un adaptador de canal de Claude Code: las herramientas MCP estándar siguen disponibles, pero los mensajes entrantes en directo también pueden llegar como notificaciones MCP específicas de Claude.

Cuando el modo de canal de Claude está habilitado, el servidor anuncia capacidades experimentales de Claude y puede emitir:

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

Comportamiento actual del puente:

• los mensajes de transcripción user entrantes se reenvían como notifications/claude/channel
• las solicitudes de permisos de Claude recibidas mediante MCP se registran en memoria
• si el propietario del comando en la conversación vinculada envía posteriormente yes <id> o no <id> (<id> es el id. de solicitud de 5 letras, sin incluir l), el puente lo convierte en notifications/claude/channel/permission
• estas notificaciones solo están disponibles durante la sesión activa; si el cliente MCP se desconecta, no hay ningún destino push

Este comportamiento es específico del cliente de forma intencionada. Los clientes MCP genéricos deben utilizar las herramientas de sondeo estándar.

Configuración del cliente MCP

Ejemplo de configuración de un cliente stdio:

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

Para la mayoría de los clientes MCP genéricos, comience con la superficie de herramientas estándar e ignore el modo Claude. Active el modo Claude solo para clientes que realmente comprendan los métodos de notificación específicos de Claude.

Opciones

openclaw mcp serve admite:

Límite de seguridad y confianza

El puente no inventa el enrutamiento. Solo expone conversaciones que el Gateway ya sabe cómo enrutar.

Esto significa lo siguiente:

• las listas de remitentes permitidos, el emparejamiento y la confianza a nivel de canal siguen perteneciendo a la configuración subyacente del canal de OpenClaw
• messages_send solo puede responder mediante una ruta almacenada existente
• el estado de aprobación solo está activo y en memoria durante la sesión actual del puente
• la autenticación del puente debe usar los mismos controles de token o contraseña del Gateway en los que se confiaría para cualquier otro cliente remoto del Gateway

Si falta una conversación en conversations_list, la causa habitual no es la configuración de MCP. Se debe a metadatos de ruta ausentes o incompletos en la sesión subyacente del Gateway.

Pruebas

OpenClaw incluye una prueba de humo determinista de Docker para este puente:

pnpm test:docker:mcp-channels

Esta prueba de humo ejecuta un único contenedor: inicializa el estado de la conversación, inicia el Gateway, después genera openclaw mcp serve como proceso secundario mediante stdio y lo controla como cliente MCP. Verifica el descubrimiento de conversaciones, la lectura de transcripciones, la lectura de metadatos de archivos adjuntos, el comportamiento de la cola de eventos en vivo y las notificaciones de canales y permisos al estilo de Claude mediante el puente MCP de stdio real. El enrutamiento de envíos salientes (messages_send reutilizando la ruta de conversación almacenada) se cubre por separado mediante pruebas unitarias en src/mcp/channel-server.test.ts.

Esta es la forma más rápida de demostrar que el puente funciona sin vincular una cuenta real de Telegram, Discord o iMessage a la ejecución de pruebas.

Para obtener un contexto de pruebas más amplio, consulte Pruebas.

Solución de problemas

OpenClaw como registro de clientes MCP

Esta es la ruta de openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload y unset.

Estos comandos no exponen OpenClaw mediante MCP. Administran las definiciones de servidores MCP gestionadas por OpenClaw en mcp.servers dentro de la configuración de OpenClaw. No leen los servidores de mcporter desde config/mcporter.json.

Estas definiciones guardadas están destinadas a entornos de ejecución que OpenClaw inicia o configura posteriormente, como OpenClaw integrado y otros adaptadores de entorno de ejecución. OpenClaw almacena las definiciones de forma centralizada para que esos entornos de ejecución no necesiten mantener sus propias listas duplicadas de servidores MCP.

Los adaptadores de entorno de ejecución pueden normalizar este registro compartido con la forma que espera su cliente posterior. Por ejemplo, OpenClaw integrado consume directamente los valores transport de OpenClaw, mientras que Claude Code y Gemini reciben valores type nativos de la CLI, como http, sse o stdio.

El servidor de aplicaciones de Codex también respeta un bloque opcional codex en cada servidor. Se trata de metadatos de proyección de OpenClaw solo para hilos del servidor de aplicaciones de Codex; no cambia las sesiones ACP, la configuración genérica del entorno de Codex ni otros adaptadores de entorno de ejecución. Utilice valores codex.agents no vacíos para proyectar un servidor únicamente en identificadores específicos de agentes de OpenClaw. Las listas de agentes vacías, en blanco o no válidas son rechazadas por la validación de la configuración y omitidas por la ruta de proyección del entorno de ejecución, en lugar de convertirse en globales. Utilice codex.defaultToolsApprovalMode (auto, prompt o approve) para emitir el valor nativo default_tools_approval_mode de Codex para un servidor de confianza. OpenClaw elimina los metadatos codex antes de entregar la configuración nativa mcp_servers a Codex.

Definiciones de servidores MCP guardadas

Comandos:

• 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>

Notas:

• list ordena los nombres de los servidores.
• show sin un nombre muestra el objeto completo del servidor MCP configurado.
• status clasifica los transportes configurados sin conectarse. --verbose incluye los detalles resueltos de inicio, tiempo de espera, OAuth, filtros y llamadas paralelas.
• doctor realiza comprobaciones estáticas sin conectarse. Añada --probe cuando el comando también deba verificar que los servidores habilitados se conectan.
• probe se conecta e informa de los recuentos de herramientas, la compatibilidad con recursos e indicaciones, la compatibilidad con cambios en la lista y los diagnósticos.
• add acepta indicadores de stdio como --command, --arg, --env y --cwd, o indicadores HTTP como --url, --transport, --header, --auth oauth, además de indicadores de TLS, tiempo de espera y selección de herramientas.
• set espera un valor de objeto JSON en la línea de comandos.
• configure actualiza la habilitación, los filtros de herramientas, los tiempos de espera, OAuth, TLS y las indicaciones de llamadas paralelas a herramientas sin sustituir toda la definición del servidor. Añada --probe para verificar el servidor actualizado antes de guardarlo.
• tools actualiza los filtros de herramientas por servidor. Las entradas de inclusión y exclusión son nombres de herramientas MCP y patrones glob simples *.
• login ejecuta el flujo OAuth para servidores HTTP configurados con auth: "oauth". La primera ejecución muestra una URL de autorización; vuelva a ejecutarlo con --code después de la aprobación.
• logout borra las credenciales OAuth almacenadas del servidor indicado sin eliminar la definición guardada del servidor.
• reload elimina los entornos de ejecución MCP en proceso almacenados en caché únicamente para el proceso actual de la CLI. Los procesos del Gateway o de agentes que se ejecuten en otro proceso siguen necesitando su propia ruta de recarga o reinicio.
• Utilice transport: "streamable-http" para servidores MCP HTTP transmitibles. openclaw mcp set también normaliza el valor type: "http" nativo de la CLI a la misma forma de configuración canónica por compatibilidad.
• unset falla si el servidor indicado no existe.

Ejemplos:

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

Recetas habituales de servidores

Estos ejemplos solo guardan definiciones de servidores. Ejecute openclaw mcp doctor --probe después para comprobar que el servidor se inicia y expone herramientas.

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

Estructuras de salida JSON

Utilice --json para scripts y paneles. Los conjuntos de campos pueden ampliarse con el tiempo, por lo que los consumidores deben ignorar las claves desconocidas.

{  "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": "Las credenciales de OAuth no están autorizadas; ejecute 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": []}

Ejemplo de estructura de configuración:

{  "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_*"]        }      }    }  }}

Transporte Stdio

Inicia un proceso secundario local y se comunica mediante stdin/stdout.

Transporte SSE/HTTP

Se conecta a un servidor MCP remoto mediante eventos enviados por el servidor a través de HTTP.

Ejemplo:

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

Los valores confidenciales de url (información del usuario) y headers se ocultan en los registros y en la salida de estado. openclaw mcp doctor advierte cuando las entradas headers o env que parecen confidenciales contienen valores literales, para que los operadores puedan trasladar esos valores fuera de la configuración confirmada en el repositorio.

Flujo de trabajo de OAuth

OAuth se utiliza para servidores MCP HTTP que anuncian el flujo OAuth de MCP. Los encabezados estáticos Authorization se ignoran en un servidor mientras auth: "oauth" está habilitado. Las credenciales guardadas mediante openclaw mcp login funcionan con MCP integrado, ejecutores de la CLI y el servidor de aplicaciones local de Codex.

Hasta que haya credenciales disponibles, OpenClaw omite únicamente ese servidor MCP del entorno de ejecución del agente, en lugar de provocar un error en el turno del agente. El operador, o un agente con acceso al shell, puede ejecutar entonces openclaw mcp login <name> y utilizar el servidor en un turno posterior.

Cuando un servicio MCP remoto ya utiliza un perfil de autenticación independiente de OpenClaw con capacidad de renovación, puede establecer opcionalmente oauth.authProfileId. OpenClaw renueva cualquiera de las fuentes de credenciales antes de la proyección en el entorno de ejecución y solo pasa el token de acceso actual al cliente MCP descendente.

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 el proveedor rota los tokens o el estado de autorización queda bloqueado, ejecuta openclaw mcp logout <name> y, a continuación, repite login. logout puede borrar las credenciales de un servidor HTTP guardado incluso después de que auth: "oauth" se haya eliminado de la configuración, siempre que el nombre y la URL del servidor sigan identificando la entrada del almacén de credenciales.

Transporte HTTP con streaming

streamable-http es una opción de transporte adicional junto con sse y stdio. Utiliza streaming HTTP para la comunicación bidireccional con servidores MCP remotos.

La configuración de OpenClaw utiliza transport: "streamable-http" como grafía canónica. Los valores type: "http" de MCP nativos de la CLI se aceptan cuando se guardan mediante openclaw mcp set y openclaw doctor --fix los repara en la configuración existente, pero transport es lo que consume directamente OpenClaw integrado.

Ejemplo:

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

Interfaz de control

La interfaz de control del navegador incluye una página de configuración dedicada a MCP en /settings/mcp; la ruta anterior /mcp sigue siendo un alias. La página muestra el número de servidores configurados, resúmenes de servidores habilitados, OAuth y filtros, filas de transporte por servidor, controles para habilitar o deshabilitar, comandos comunes de la CLI y un editor limitado a la sección de configuración mcp.

Utiliza la página para realizar modificaciones operativas y consultar rápidamente el inventario. Utiliza openclaw mcp doctor --probe o openclaw mcp probe cuando necesites una prueba activa del servidor.

Flujo de trabajo del operador:

1. Abre la interfaz de control y selecciona MCP.
2. Revisa las tarjetas de resumen de servidores totales, habilitados, con OAuth y filtrados.
3. Utiliza la fila de cada servidor para consultar indicaciones sobre el transporte, la autenticación, los filtros, el tiempo de espera y los comandos.
4. Alterna la habilitación cuando quieras conservar una definición, pero excluirla del descubrimiento en tiempo de ejecución.
5. Edita la sección de configuración delimitada mcp para realizar cambios estructurales, como añadir servidores, encabezados, TLS, metadatos OAuth o filtros de herramientas.
6. Selecciona Guardar para conservar únicamente la configuración o Guardar y publicar para aplicarla mediante la ruta de configuración del Gateway.
7. Ejecuta openclaw mcp doctor --probe cuando necesites una prueba activa de que el servidor editado se inicia y enumera las herramientas.

Notas:

• los fragmentos de comandos ponen entre comillas los nombres de los servidores para que los nombres poco habituales puedan seguir copiándose en un shell
• los valores mostrados similares a URL se ocultan antes de renderizarlos cuando contienen credenciales integradas
• la página no inicia por sí sola los transportes MCP
• los entornos de ejecución activos pueden requerir openclaw mcp reload, la publicación de la configuración del Gateway o el reinicio del proceso, según qué proceso sea el propietario de los clientes MCP

Aplicaciones MCP

OpenClaw puede renderizar herramientas que implementen la extensión MCP Apps estable. Las aplicaciones son opcionales porque su HTML procede del servidor MCP configurado y puede solicitar herramientas o recursos visibles para la aplicación desde ese mismo servidor.

Habilita el puente del host:

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

Reinicia el Gateway después de cambiar esta configuración. Cuando está habilitada, OpenClaw inicia un listener HTTP(S) exclusivo para el entorno aislado en el puerto del Gateway más uno (para el Gateway predeterminado, 18790). La interfaz de control carga las aplicaciones desde ese origen independiente; el listener nunca sirve la interfaz de control, las rutas autenticadas del Gateway ni datos de usuario.

Las conexiones directas al Gateway necesitan acceso a ambos puertos. Si un proxy inverso o terminador TLS expone la interfaz de control, asigna a las aplicaciones un origen público dedicado y redirige únicamente ese origen al listener del entorno aislado:

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

El origen del entorno aislado debe ser distinto del origen de la interfaz de control. No alojes en él otro contenido autenticado o confidencial.

Por ejemplo, la demostración básica oficial de React puede configurarse así:

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

Comportamiento y límites de seguridad:

• OpenClaw anuncia la extensión io.modelcontextprotocol/ui solo cuando las aplicaciones están habilitadas.
• Solo se renderizan los recursos ui:// con el tipo MIME exacto text/html;profile=mcp-app.
• Los recursos de la interfaz de usuario tienen un límite de 2 MiB, se sitúan detrás de un proxy de doble iframe en un origen externo dedicado, se cargan en un origen interno opaco de la aplicación y se restringen mediante una CSP derivada de los metadatos del recurso.
• Las herramientas exclusivas de la aplicación (_meta.ui.visibility: ["app"]) no se incluyen en las listas de herramientas del modelo. Las aplicaciones solo pueden llamar a herramientas visibles para la aplicación en su servidor propietario que también cumplan la política efectiva de herramientas de OpenClaw para la ejecución que creó la vista.
• Los permisos de la aplicación vinculados al origen, como la cámara, el micrófono y la geolocalización, no se conceden mientras los documentos internos de la aplicación utilicen orígenes opacos para el aislamiento entre aplicaciones.
• El HTML de la aplicación, los argumentos completos de las herramientas y los resultados sin procesar permanecen en una concesión de vista limitada en memoria durante diez minutos y no se escriben en disco ni se copian en los metadatos de vista previa de la transcripción. La transcripción solo almacena un descriptor limitado de servidor, herramienta y recurso vinculado al ID original de la llamada a la herramienta. Después de reiniciar el Gateway, la interfaz de control puede verificar ese descriptor con la transcripción de la sesión autenticada y volver a obtener el recurso ui://; las vistas reconstruidas son de solo lectura hasta que una nueva ejecución establezca los permisos actuales de las herramientas.
• openclaw security audit muestra una advertencia mientras el puente está habilitado. Deshabilítalo con openclaw config set mcp.apps.enabled false --strict-json cuando no sea necesario.

Límites actuales

Esta página documenta el puente tal como se distribuye actualmente.

Límites actuales:

• el descubrimiento de conversaciones depende de los metadatos existentes de las rutas de sesión del Gateway
• no existe ningún protocolo genérico de envío más allá del adaptador específico de Claude
• todavía no hay herramientas para editar mensajes ni añadir reacciones
• el transporte HTTP/SSE/streamable-http se conecta a un único servidor remoto; todavía no existe multiplexación ascendente
• permissions_list_open solo incluye las aprobaciones observadas mientras el puente está conectado

Contenido relacionado

• Referencia de la CLI
• Plugins