Integración MCP: dale a Claw una caja de herramientas externa
El navegador de la lección anterior le dio a Claw manos para navegar; en esta lección le conectamos una caja de herramientas externa. La documentación oficial de MCP (Model Context Protocol) resume su esencia en una frase: «an agent borrows tools from another program»——un agent toma prestadas las herramientas de otro programa. Los servidores MCP exponen herramientas, recursos y prompts; cuando OpenClaw se conecta a uno, esas herramientas aparecen en el catálogo de herramientas de tu agent, listas para usar cuando quieras.
La integración MCP de OpenClaw tiene tres caras: clics en la Control UI, la línea de comandos openclaw mcp, el archivo de configuración mcp.servers——todos los caminos llevan al mismo sitio: escriben la misma configuración. Además hay una dirección inversa: openclaw mcp serve expone en sentido inverso las conversaciones de los canales de OpenClaw a clientes MCP como Claude Code / Codex. Todos los ejemplos se basan en OpenClaw v2026.10.9.
Qué podrás hacer al terminar
- Montar servidores MCP en OpenClaw de tres formas (Control UI /
openclaw mcpCLI /mcp.serversarchivo de configuración) - Verificar con
openclaw mcp doctor <name> --probeque el servidor está realmente en línea y realmente expone herramientas - Exponer al agent solo las herramientas necesarias con
--include/toolFilter/openclaw mcp tools - Completar el inicio de sesión para servidores HTTP remotos que requieren OAuth
- Exponer en sentido inverso las conversaciones de los canales OpenClaw a Claude Code / Codex con
openclaw mcp serve
Tu situación actual
- Claw puede chatear, ejecutar comandos y navegar, pero en cuanto toca sistemas internos o fuentes de datos específicas se queda sin opciones——no tiene las herramientas correspondientes
- Encontraste un servidor MCP existente, pero no sabes cómo conectarlo a OpenClaw: dónde escribir la configuración, qué formato tiene, cómo verificarlo después de conectar, todo a base de adivinar
- Te preocupa que las herramientas externas queden sin control: al conectar un servidor de terceros, ¿sus herramientas podrían saltarse los permisos que configuré?
Cuándo usar esta técnica
Cuando necesitas:
- Dar a Claw capacidades que las herramientas integradas no tienen: leer y escribir directorios específicos, memorias externas, APIs internas, control del escritorio……
- Reutilizar servidores existentes del ecosistema MCP——
npxse montan con un solo comando, sin escribir plugins propios - Compartir la misma definición de herramientas entre varios agents / varios runtimes——OpenClaw las almacena de forma centralizada en
mcp.servers, y los runtimes no tienen que mantener cada uno su copia
Y además no quieres:
- Modificar el núcleo de OpenClaw o escribir un plugin por cada capacidad nueva
- Meter a la fuerza el uso de las herramientas en los prompts——las herramientas MCP traen su propio schema, el agent las descubre automáticamente
🎒 Preparativos antes de empezar
- Haber leído la introducción de esta etapa Flujos de trabajo eficientes: automatización, navegador y MCP
- OpenClaw instalado y con el onboarding completado (si no lo tienes, mira primero Instalación: 5 minutos para ponerlo en marcha OpenClaw)
- Tener a mano la información del servidor que quieres montar: el comando de arranque de un servidor local stdio, o la URL de un servidor HTTP remoto
- Saber abrir la Control UI (se usará en la forma B)
Idea central
Primero establece el sentido de la dirección. MCP tiene dos direcciones, no las confundas:
| Dirección | Quién es el servidor MCP | Para qué sirve | Punto de entrada |
|---|---|---|---|
| Integración (eje de esta lección) | Un programa de terceros | OpenClaw se conecta a él y presta sus herramientas a tu agent | Settings → MCP / openclaw mcp add / mcp.servers |
| Exposición inversa (avanzado) | OpenClaw mismo | Otros clientes MCP vienen a leer / enviar las conversaciones de los canales de OpenClaw | openclaw mcp serve |
Tres líneas rojas escritas explícitamente en la documentación oficial:
- Las definiciones de servidores se almacenan de forma unificada bajo
mcp.serversde la configuración; las tres caras de integración escriben la misma cosa; - Las herramientas MCPpasan por el mismo conjunto de controles tool-profile / tool-policy—«connecting a server does not bypass your policy», conectar no equivale a autorizar;
- No escribas credenciales como literales en la configuración: los headers sensibles y las variables de entorno se guardan con el mecanismo de secretos admitido.
Tres tipos de transporte, elige según dónde está el servidor:
| Transporte | Adecuado para | Qué hay que rellenar |
|---|---|---|
| Stdio | Servidores iniciados por un comando local | command + args (opcional cwd / env) |
| Streamable HTTP | Servidores remotos | http(s):// URL |
| SSE | Servidores remotos antiguos | http(s):// URL |
La regla en una frase: command (stdio) y URL (familia HTTP), solo uno de los dos; si escribes ambos, la validación de configuración lo rechazará; enabled: false conserva la definición pero no conecta; el nombre de servidor __proto__ es una palabra reservada, usa otro nombre.
Tres vías de integración, elige según tu preferencia:
| Vía de integración | Para quién | Características |
|---|---|---|
| Control UI (Settings → MCP) | Quien no quiere tocar la terminal | Se puede modificar con el Gateway en ejecución, OAuth con un clic en el navegador |
CLI (openclaw mcp) | Quien quiere copiar y pegar, automatizar con scripts | Los comandos de escritura requieren estado exclusivo, detén primero el Gateway (ver el problema común 1) |
Archivo de configuración (mcp.servers) | Quien necesita control de versiones, inicialización en lote | Campos más completos, edición directa |
Hazlo conmigo
Paso 1: conoce el estado de MCP en OpenClaw (openclaw mcp status --verbose)
Por qué: antes de actuar, mira qué hay en casa. status solo lee la configuración y no conecta ningún servidor, se puede ejecutar con el Gateway en marcha.
openclaw mcp status --verboseDeberías ver: una lista de las definiciones de servidores guardadas: tipo de transporte, parámetros de arranque, tiempos de espera, estado de OAuth y filtros de herramientas de cada servidor. En una instalación nueva la lista está vacía, justo lo ideal para empezar de cero.
💡 Si dudas, ejecuta esto primero
La recomendación oficial es la misma: si no sabes qué camino tomar, ejecuta primero openclaw mcp status --verbose: te dice qué hay guardado en OpenClaw sin iniciar ningún servidor MCP.
Paso 2: añade el primer servidor MCP (elige cualquiera de las tres formas)
Por qué: usa el servidor memory de las recetas oficiales como primero: npx lo levanta con un solo comando, configuración cero. Las tres formas escriben el mismo mcp.servers, elige la que te resulte cómoda.
Forma A (recomendada): CLI, resuelto en una ventana de parada
Por qué va envuelto en stop / restart: add este tipo de comandos de escritura requiere acceso exclusivo al directorio de estado; si el Gateway está en ejecución y lo retiene, rechazará la escritura y pedirá detenerlo primero, es de diseño, no un fallo.
openclaw gateway stop
openclaw mcp add memory \
--command npx \
--arg -y \
--arg @modelcontextprotocol/server-memory
openclaw gateway restartDeberías ver: add hace primero una comprobación y luego guarda la definición (lleva comprobación por defecto, salvo --no-probe o si hay que completar OAuth antes); tras guardar, restart deja el Gateway corriendo con la nueva definición.
- Comprobación rápida:
openclaw mcp listpermite vermemory
Forma B: añadir directamente en runtime desde Control UI
- Abre Control UI y entra en Settings → MCP (también vale escribir
/settings/mcpen la barra de direcciones del navegador o el alias/mcp). - En Configured servers elige Add server.
- Pon un nombre único y elige transporte: Streamable HTTP / SSE / Stdio.
- Para transportes de la familia HTTP rellena el
http://ohttps://URL del servidor; para stdio, el comando de arranque y sus argumentos. - Elige Add server: la definición se escribe en
mcp.serversa través del Gateway.
Deberías ver: el servidor aparece en la lista, cada fila permite activarlo, desactivarlo o eliminarlo; los elementos avanzados como headers, variables de entorno, OAuth, TLS y tiempos de espera están en el editor de configuración por secciones al final de la página.
También se puede añadir desde la ventana de chat: + → Plugins → Add MCP server… (requiere permisos de administrador), con ámbito This session (solo esta sesión) o Everywhere (global).
Forma C: escribir directamente el archivo de configuración
El mismo servidor memory, escrito en mcp.servers queda así (JSON5):
{
mcp: {
servers: {
memory: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-memory"],
enabled: true,
},
},
},
}Deberías ver: tras guardar, en instalaciones con recarga en caliente del Gateway el cambio surte efecto de inmediato: los servidores modificados o eliminados se retiran al instante y el descubrimiento de herramientas del siguiente turno usa la nueva definición; los servidores intactos mantienen conexión y caché.
Paso 3: revisión de salud, doctor --probe demuestra que el servidor está realmente en línea
Por qué: palabras textuales de la documentación oficial: «Saving a definition proves nothing about reachability»: guardar una definición no demuestra nada, lo que cuenta es que se pueda conectar. La escalera de diagnóstico, de lo ligero a lo pesado:
openclaw mcp status --verbose # 只读配置,随时能跑
openclaw mcp doctor memory # 静态检查,随时能跑
openclaw mcp doctor memory --probe # 真实连接,要独占状态(Gateway 在跑会拒绝)
openclaw mcp probe memory # 只做真实连接、列工具(同样要独占状态)Deberías ver: doctor comprueba primero problemas locales de configuración: comando stdio ausente, cwd inexistente, archivos TLS faltantes, servidor deshabilitado, valores sensibles en texto plano, autorización OAuth incompleta; --probe luego abre una conexión real e informa de las herramientas y otras capacidades que expone el servidor.
Si el servidor no se puede conectar temporalmente, no te apresures a diagnosticar: OpenClaw el cliente integrado reintenta con retroceso exponencial: desde 30 segundos, duplicando en cada intento, hasta 10 minutos como máximo; la recuperación corre en segundo plano, las herramientas quedan disponibles en el límite del siguiente turno y no bloquea la conversación actual.
- Comprobación rápida: en la salida de
doctor --probese ve la lista de herramientas
Paso 4: filtra las herramientas, expón solo las necesarias
Por qué: un servidor puede traer un montón de herramientas; exponerlas todas es ruidoso e inseguro. El servidor de sistema de archivos es el ejemplo típico de la documentación oficial: deja solo lectura y búsqueda, sin escritura:
openclaw gateway stop
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 gateway restartDeberías ver: doctor files --probe se conecta al servidor y reporta las herramientas; --include el filtrado ocurre antes de que las herramientas entren al catálogo del agent, así que las herramientas de escritura no aparecen. La recomendación oficial es acotar el servidor de sistema de archivos al árbol de directorios mínimo que el agent necesita.
Para ajustar a posteriori servidores ya guardados se usa tools (también requiere ventana de parada):
openclaw mcp tools files --include 'read_file,list_directory,search_files'
openclaw mcp tools files --clear # 清除过滤En el archivo de configuración corresponden a toolFilter.include / toolFilter.exclude, con soporte de comodines *. En la sesión también se puede afinar: ventana de chat + → Plugins → Tool access, donde se puede revisar o deshabilitar herramienta por herramienta en esa sesión.
Paso 5: conectar un servidor remoto que requiere inicio de sesión OAuth
Por qué: los servidores HTTP remotos suelen usar autenticación OAuth. Tomando como ejemplo la receta oficial del servidor de docs, se declara directamente con add:
openclaw gateway stop
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 login docs
openclaw gateway restartPor qué hay que parar: openclaw mcp login solo se ejecuta en estado offline (necesita acceso exclusivo al directorio de estado para completar el callback de OAuth).
Deberías ver: el terminal imprime la URL de autorización; tras completar la autorización en el navegador, OpenClaw normalmente captura automáticamente la redirección de loopback y guarda las credenciales. Cuando el navegador no alcanza el listener del callback (entornos remotos o sin interfaz), usa el comando --code impreso como alternativa.
En la Control UI es más sencillo: en Settings → MCP el administrador puede seleccionar directamente Sign in para servidores OAuth habilitados; tras aprobar el acceso en el navegador, basta con volver a Settings.
Punto de control ✅
openclaw mcp status --verbosepuede listar tus servidores guardados y sus tipos de transporteopenclaw mcp doctor <name> --probese conecta al servidor y lista sus herramientas- En una conversación, pide a Claw usar una herramienta nueva y la invoca con éxito
- Has restringido la exposición de herramientas con
openclaw mcp tools <name> --include … - Puedes explicar por qué los comandos CLI de escritura exigen detener primero el Gateway (o usar la Control UI en su lugar)
Avisos de errores comunes
❌ Con el Gateway en ejecución, los comandos CLI de escritura son rechazados
add / set / configure / tools / unset / login / logout / probe / doctor --probe todos requieren acceso exclusivo al directorio de estado. Si el Gateway está en ejecución y lo retiene, el comando rechaza la escritura y muestra un aviso de «detén primero y reintenta».
La forma correcta: o bien openclaw gateway stop → operación → openclaw gateway restart, o usar directamente la Control UI (Settings → MCP admite modificación e inicio de sesión en tiempo de ejecución). list / show / status / doctor (sin --probe) no se ven afectados y se pueden ejecutar en cualquier momento con el Gateway corriendo.
❌ El servidor aparece en la lista, pero no hay herramientas en la conversación
Guardado ≠ accesible. Orden de diagnóstico:
openclaw mcp doctor <name> --probe- Se conecta pero hay menos herramientas de lo esperado → revisa si
toolFilter.include/toolFilter.excludeestán filtrando demasiado - Los servidores con
enabled: falseconservan la definición pero no se conectan y no entran en el descubrimiento de herramientas - Si todo está normal y aún no funciona → puede que los cambios no hayan llegado al agent en ejecución:
openclaw mcp reloadsolo refresca el runtime del proceso CLI actual; el Gateway o los agents en otros lugares requieren su propio reload / publicación de configuración / reinicio
❌ El servidor stdio no arranca
Tres causas habituales, todas detectables con doctor:
commandno se resuelve en el entorno del proceso del Gateway: que puedas ejecutarlo en tu propia shell no significa que funcione en el entorno del Gateway- El directorio
cwdno existe - Parámetros en el lugar equivocado: los parámetros pertenecen a
args, no los concatenes encommand; untransport: "stdio"explícito debe tener un command no vacío
❌ El servidor HTTP devuelve 401 (authentication refused)
Los registros de arranque y el diagnóstico de directorio reportarán authentication refused (401). Esto significa que el servidor exige autenticación, no que OpenClaw esté roto:
- Servidores OAuth: confirma que estén configurados
auth: "oauth"y los metadatosoauthrequeridos, y luego sigue el flujo de inicio de sesión del paso 5 - Credenciales estáticas: revisa la configuración de headers / credenciales de ese servidor en
mcp.servers; y no escribas el token en texto plano en la configuración, guárdalo con el mecanismo de secrets
Técnicas avanzadas (opcional)
**En sentido inverso: exponer conversaciones de canales a Claude Code / Codex. ** openclaw mcp serve permite que OpenClaw actúe él mismo como servidor MCP (stdio): el cliente MCP inicia y retiene este proceso, el puente se conecta vía WebSocket al Gateway local o remoto, y convierte las sesiones de canal ya enrutadas en sesiones MCP.
openclaw mcp serve # 本地 Gateway
openclaw mcp serve --url wss://gateway-host:18789 \
--token-file ~/.openclaw/gateway.token # 远程 Gateway(token)Herramientas expuestas por el puente: conversations_list, conversation_get, messages_read, attachments_fetch, events_poll, events_wait, messages_send, más permissions_list_open / permissions_respond para gestionar aprobaciones de exec y de plugins. Ten en cuenta que la cola de eventos es en tiempo real: al romperse el puente se pierde; los mensajes históricos se leen con messages_read.
**Definir el modo de aprobación para servidores de confianza. ** La aprobación de herramientas MCP de Codex sigue por defecto la postura de permisos de la sesión; los servidores de confianza pueden relajarse explícitamente:
openclaw mcp add memory \
--command npx \
--arg -y \
--arg @modelcontextprotocol/server-memory \
--approval approveTres niveles: approve (omite la aprobación por cada llamada, solo para servidores de confianza) / prompt (pregunta cada vez) / auto (según las anotaciones de seguridad de la herramienta). Para servidores ya guardados se cambia individualmente con openclaw mcp configure <name> --approval ….
**Timeouts y concurrencia por servidor. ** connectionTimeoutMs / requestTimeoutMs establecen los timeouts de conexión y de petición (milisegundos); supportsParallelToolCalls: true marca los servidores que el adaptador puede invocar en concurrente.
Resumen de la lección
✅ MCP = el protocolo con el que un agent toma prestadas herramientas de otros programas. Cuando OpenClaw se conecta a un servidor MCP, las herramientas entran automáticamente al catálogo del agent y, además, pasan por el mismo conjunto de controles tool-profile / tool-policy: la integración no esquiva tus políticas.
✅ La integración MCP de OpenClaw es trinidad con tres caras: Control UI (Settings → MCP), CLI (openclaw mcp), archivo de configuración (mcp.servers); todas escriben la misma configuración.
✅ Cadena de verificación: status --verbose (configuración de solo lectura) → doctor (comprobación estática) → doctor --probe / probe (conexión real que lista herramientas). Guardar una definición no prueba nada.
✅ Reduce la superficie expuesta: --include / toolFilter / openclaw mcp tools; limita el servidor de sistema de archivos al árbol de directorios mínimo; dentro de la sesión usa + → Plugins → Tool access para desactivarlos uno por uno.
✅ Los comandos CLI de escritura (add / set / configure / tools / unset / login / logout / probe / doctor --probe) requieren estado exclusivo: si Gateway se está ejecutando, deténlo primero antes de reintentar, o usa la Control UI.
✅ En la dirección inversa con openclaw mcp serve: OpenClaw actúa como servidor MCP, prestando las conversaciones del canal a Claude Code / Codex.
| Campo de configuración clave | Valor recomendado | Descripción |
|---|---|---|
mcp.servers.<name>.transport | streamable-http / sse / stdio | Para servidores remotos usa la familia HTTP, para comandos locales usa stdio |
command + args vs url | Elige uno de los dos | En stdio se pone el comando y los argumentos, en HTTP la URL; si se escriben ambos, la validación lo rechaza |
toolFilter.include / exclude | Deja solo las herramientas necesarias (admite comodines *) | El filtrado ocurre antes de que las herramientas entren al catálogo |
enabled | true / false | false conserva la definición pero no se conecta |
connectionTimeoutMs / requestTimeoutMs | 5000 / 20000 | Tiempo de espera (ms) por conexión / solicitud de cada servidor |
auth | "oauth" | OAuth para servidores HTTP, se usa con openclaw mcp login |
codex.defaultToolsApprovalMode | approve / prompt / auto | Modo de aprobación de herramientas de Codex, se escribe con --approval |
Referencia rápida de CLI: openclaw mcp list / show / status / doctor / probe / add / set / configure / tools / login / logout / reload / unset. La tabla completa de comandos está en Referencia rápida de comandos y configuración CLI.
Vista previa de la próxima lección
El trío del flujo de trabajo ya está completo: tareas programadas controla cuándo actuar, navegador controla la obtención de datos en la web, y MCP controla las capacidades externas. En la próxima lección, Práctica por escenarios: elige tu ruta, escoge una ruta según tu perfil y combina el trío en trabajo real.
Aprenderás:
- Matriz de integración con IM nacionales: cómo conectar WeCom, Feishu, WeChat / QQ / Yuanbao, respectivamente
- Combina programación + web en informe matutino diario y monitoreo web
- Haz que Claw escriba código y vigile PR: escritura de código y turno de GitHub
- Despliegue en servidor: mantén a Claw en línea 7×24 en VPS / Docker
Tutoriales relacionados
- Control del navegador: haz que Claw navegue y opere por ti——capacidad web integrada, complementaria de los complementos externos MCP
- Tareas programadas Automations: cron, recordatorios y activación por Webhook——herramientas MCP + activación programada = pipeline sin supervisión
- Primeros pasos con Skills: instalación, uso y configuración——otra forma de extender, cómo elegir entre skills y herramientas MCP