MCP

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

​

Elegir la ruta MCP adecuada

​

OpenClaw como servidor MCP

​

Cuándo utilizar serve

• 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 independientes para cada canal

​

Funcionamiento

​

Elegir un modo de cliente

​

Lo que expone serve

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

• enumerar conversaciones enrutadas recientes
• leer el historial reciente de transcripciones
• 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 --verbose
openclaw mcp serve --claude-channel-mode off

​

Herramientas del puente

​

Modelo de eventos

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

​

Notificaciones del canal de Claude

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

• los mensajes entrantes de transcripción user 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 identificador de solicitud de 5 letras, sin incluir l), el puente lo convierte en notifications/claude/channel/permission
• estas notificaciones solo existen durante la sesión activa; si el cliente MCP se desconecta, no existe ningún destino push

​

Configuración del cliente MCP

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

​

Opciones

​

Límite de seguridad y confianza

• 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 en memoria durante la sesión actual del puente
• la autenticación del puente debe utilizar los mismos controles de token o contraseña del Gateway en los que confiaría para cualquier otro cliente remoto del Gateway

​

Pruebas

pnpm test:docker:mcp-channels

​

Solución de problemas

​

OpenClaw como registro de clientes MCP

​

Definiciones de servidores MCP guardadas

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

• 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 detalles resueltos de inicio, tiempo de espera, OAuth, filtros y llamadas paralelas, incluso cuando los tokens OAuth almacenados requieren autorización adicional. Los argumentos de stdio que contienen credenciales se ocultan en la salida de texto y JSON.
• 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 del número de herramientas, la compatibilidad con recursos/indicaciones, la compatibilidad con cambios de 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, 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 de cada servidor. Las entradas de inclusión/exclusión son nombres de herramientas MCP y patrones glob sencillos *.
• login ejecuta el flujo OAuth para los 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 descarta 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 seguirán 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.

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw 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 docs
openclaw mcp logout docs
openclaw mcp unset context7

​

Recetas comunes de servidores

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-memory
openclaw 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.example
openclaw 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,get_window_state,click,type_text'
openclaw mcp doctor cua-driver --probe

​

Estructuras de salida JSON

{
  "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,
        "requiresAuthorization": false,
        "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; ejecuta 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": []
}

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http",
        "requestTimeoutMs": 20000,
        "connectionTimeoutMs": 5000,
        "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

​

Transporte SSE/HTTP

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

​

Flujo de trabajo de OAuth

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 --verbose
openclaw mcp doctor docs --probe

openclaw mcp logout docs

​

Transporte HTTP transmisible

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 30000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

​

Interfaz de control

1. Abra la interfaz de control y elija MCP.
2. Revise las tarjetas de resumen de servidores totales, habilitados, con OAuth y filtrados.
3. Use cada fila de servidor para consultar el transporte, la autenticación, el filtro, el tiempo de espera y las sugerencias de comandos.
4. Alterne la habilitación cuando desee conservar una definición, pero excluirla del descubrimiento en tiempo de ejecución.
5. Edite la sección de configuración limitada a mcp para realizar cambios estructurales, como añadir servidores, encabezados, TLS, metadatos de OAuth o filtros de herramientas.
6. Elija Guardar para conservar únicamente la configuración o Guardar y publicar para aplicarla mediante la ruta de configuración del Gateway.
7. Ejecute openclaw mcp doctor --probe cuando necesite una comprobación activa de que el servidor editado se inicia y enumera las herramientas.

• los fragmentos de comandos escriben entre comillas los nombres de los servidores para que los nombres inusuales se puedan copiar en un shell
• los valores mostrados que parecen URL se ocultan antes de representarlos cuando contienen credenciales incrustadas
• la página no inicia por sí sola los transportes MCP
• los entornos de ejecución activos pueden necesitar openclaw mcp reload, la publicación de la configuración del Gateway o un reinicio del proceso, según el proceso propietario de los clientes MCP

​

Aplicaciones MCP

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

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

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

• OpenClaw anuncia la extensión io.modelcontextprotocol/ui únicamente cuando las aplicaciones están habilitadas.
• Solo se representan 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 colocan detrás de un proxy de doble iframe en un origen externo específico, se cargan en un origen interno opaco de la aplicación y quedan restringidos por la CSP derivada de los metadatos del recurso.
• Las herramientas exclusivas de la aplicación (_meta.ui.visibility: ["app"]) no aparecen en las listas de herramientas del modelo. Las aplicaciones solo pueden llamar a herramientas visibles para aplicaciones 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 utilizan 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 en memoria limitada a diez minutos y no se escriben en el disco ni se copian en los metadatos de vista previa de la transcripción. La transcripción almacena únicamente un descriptor limitado de servidor, herramienta y recurso vinculado al ID original de la llamada a la herramienta. Tras reiniciar el Gateway, la interfaz de control puede verificar ese descriptor mediante 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.
• En las conversaciones de canal, la última vista correcta de una aplicación en un turno añade una acción del tipo Abrir aplicación a la respuesta final del asistente. Los mensajes directos de Telegram utilizan un botón nativo de Mini App; Slack y Discord representan la misma acción portátil como enlace. Los demás canales conservan el texto original de la respuesta y añaden un enlace HTTPS comprensible.
• Los enlaces de inicio del canal solo están disponibles cuando la exposición de Tailscale del Gateway ha preparado un origen HTTPS publicado. gateway.tailscale.mode: "serve" solo es accesible desde la tailnet; "funnel" es accesible desde Internet público. Un Funnel gestionado externamente y conservado por gateway.tailscale.preserveFunnel también se considera accesible desde Internet. Consulte Tailscale.
• Los tiques de inicio son opacos, se generan únicamente al materializar la respuesta final del canal y caducan después de un máximo de dos minutos o cuando caduca la concesión de vista subyacente, lo que ocurra primero. La URL no contiene credenciales bearer del Gateway, claves de sesión, metadatos de la vista, HTML de la aplicación, entradas de herramientas ni resultados de herramientas.
• Si no hay ningún origen publicado o capacidad para tiques disponible, la vista o el tique han caducado, o el transporte no puede representar controles nativos, el texto original del asistente sigue estando disponible. La interfaz de control conserva su lienzo de aplicación en línea existente y no recibe una acción de inicio duplicada.
• openclaw security audit muestra una advertencia mientras el puente está habilitado. Deshabilítelo con openclaw config set mcp.apps.enabled false --strict-json cuando no sea necesario.

​

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 un upstream multiplexado
• permissions_list_open solo incluye las aprobaciones observadas mientras el puente está conectado

​

Contenido relacionado

• Referencia de la CLI
• Plugins