MCP

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

​

Elige la ruta MCP correcta

​

OpenClaw como servidor MCP

​

Cuándo usar serve

• Codex, Claude Code u otro cliente MCP deban hablar directamente con conversaciones de canales respaldadas por OpenClaw
• ya tengas un Gateway de OpenClaw local o remoto con sesiones enrutadas
• quieras un servidor MCP que funcione en todos los backends de canales de OpenClaw en lugar de ejecutar puentes separados por canal

​

Cómo funciona

​

Elige un modo de cliente

​

Qué expone serve

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

• listar conversaciones enrutadas recientes
• leer el historial de transcripción reciente
• esperar nuevos eventos entrantes
• enviar una respuesta por la misma ruta
• ver solicitudes de aprobación que llegan 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 de canal Claude

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

• los mensajes de transcripción user entrantes se reenvían como notifications/claude/channel
• las solicitudes de permiso de Claude recibidas mediante MCP se rastrean en memoria
• si el propietario del comando en la conversación vinculada envía más adelante yes <id> o no <id> (<id> es el id de solicitud de 5 letras, excluyendo l), el puente lo convierte en notifications/claude/channel/permission
• estas notificaciones son solo para la sesión en vivo; si el cliente MCP se desconecta, no hay destino push

​

Configuración de cliente MCP

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

​

Opciones

​

Seguridad y límite de confianza

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

​

Pruebas

pnpm test:docker:mcp-channels

​

Solución de problemas

​

OpenClaw como registro de clientes MCP

​

Definiciones guardadas de servidores MCP

• 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 servidores.
• show sin un nombre imprime el objeto completo del servidor MCP configurado.
• status clasifica los transportes configurados sin conectarse. --verbose incluye detalles resueltos de lanzamiento, tiempo de espera, OAuth, filtro y llamadas paralelas.
• doctor realiza comprobaciones estáticas sin conectarse. Agrega --probe cuando el comando también deba verificar que los servidores habilitados se conectan.
• probe se conecta e informa recuentos de herramientas, compatibilidad con recursos/prompts, compatibilidad con cambios de lista y diagnósticos.
• add acepta flags stdio como --command, --arg, --env y --cwd, o flags HTTP como --url, --transport, --header, --auth oauth, TLS, tiempo de espera y flags de selección de herramientas.
• set espera un valor de objeto JSON en la línea de comandos.
• configure actualiza habilitación, filtros de herramientas, tiempos de espera, OAuth, TLS y sugerencias de llamadas paralelas a herramientas sin reemplazar toda la definición del servidor. Agrega --probe para verificar el servidor actualizado antes de guardar.
• tools actualiza los filtros de herramientas por servidor. Las entradas de inclusión/exclusión son nombres de herramientas MCP y globs simples *.
• login ejecuta el flujo OAuth para servidores HTTP configurados con auth: "oauth". La primera ejecución imprime una URL de autorización; vuelve a ejecutarlo con --code después de la aprobación.
• logout borra las credenciales OAuth almacenadas para el servidor nombrado sin quitar la definición del servidor guardada.
• reload descarta los runtimes MCP en proceso almacenados en caché solo para el proceso CLI actual. Los procesos de Gateway o agente en otro proceso siguen necesitando su propia ruta de recarga o reinicio.
• Usa transport: "streamable-http" para servidores MCP Streamable HTTP. openclaw mcp set también normaliza el type: "http" nativo de CLI a la misma forma de configuración canónica por compatibilidad.
• unset falla si el servidor nombrado 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,observe,click,type'
openclaw mcp doctor cua-driver --probe

​

Formas 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,
        "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": "OAuth credentials are not authorized; run 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",
        "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

​

Transporte SSE / HTTP

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

​

Flujo de trabajo OAuth

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

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",
        "connectTimeout": 10,
        "timeout": 30,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

​

Interfaz de control

1. Abre la UI de Control y elige MCP.
2. Revisa las tarjetas de resumen de servidores totales, habilitados, OAuth y filtrados.
3. Usa cada fila de servidor para ver indicaciones de transporte, autenticación, filtro, tiempo de espera y comando.
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 mcp delimitada para cambios estructurales como servidores nuevos, encabezados, TLS, metadatos de OAuth o filtros de herramientas.
6. Elige Guardar para persistir solo la configuración, o Guardar y publicar para aplicarla a través de la ruta de configuración del Gateway.
7. Ejecuta openclaw mcp doctor --probe cuando necesites prueba en vivo de que el servidor editado arranca y lista herramientas.

• los fragmentos de comando entrecomillan los nombres de servidores para que los nombres inusuales sigan siendo copiables en una shell
• los valores mostrados con formato similar a URL se censuran antes de renderizarse cuando contienen credenciales incrustadas
• la página no inicia transportes MCP por sí sola
• los tiempos de ejecución activos pueden necesitar openclaw mcp reload, publicación de configuración del Gateway o reinicio del proceso, según qué proceso sea dueño de los clientes MCP

​

Límites actuales

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

​

Relacionado

• Referencia de CLI
• Plugins