MCP

OmeniaClaw mcp tiene dos tareas:

• ejecutar OmeniaClaw como servidor MCP con OmeniaClaw mcp serve
• gestionar definiciones de servidores MCP salientes propiedad de OmeniaClaw con list, show, set y unset

En otras palabras:

• serve es OmeniaClaw actuando como servidor MCP
• list / show / set / unset es OmeniaClaw actuando como registro del lado del cliente MCP para otros servidores MCP que sus runtimes podrían consumir más adelante

Usa OmeniaClaw acp cuando OmeniaClaw deba alojar por sí mismo una sesión de arnés de codificación y enrutar ese runtime mediante ACP.

OmeniaClaw como servidor MCP

Esta es la ruta de OmeniaClaw mcp serve.

Cuándo usar serve

Usa OmeniaClaw mcp serve cuando:

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

Usa OmeniaClaw acp en su lugar cuando OmeniaClaw deba alojar por sí mismo el runtime de codificación y mantener la sesión del agente dentro de OmeniaClaw.

Cómo funciona

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

Elegir un modo de cliente

Usa el mismo puente de dos maneras distintas:

Qué expone serve

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

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

Esto da a los clientes MCP un lugar para:

• listar conversaciones enrutadas recientes
• leer el historial de transcripción reciente
• esperar nuevos eventos entrantes
• enviar una respuesta de vuelta por la misma ruta
• ver solicitudes de aprobación que llegan mientras el puente está conectado

Uso

OmeniaClaw mcp serve

OmeniaClaw mcp serve --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token

OmeniaClaw mcp serve --url wss://gateway-host:18789 --password-file ~/.OmeniaClaw/gateway.password

OmeniaClaw mcp serve --verboseOmeniaClaw mcp serve --claude-channel-mode off

Herramientas del puente

El puente actual expone estas herramientas MCP:

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 de canal Claude

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

Cuando el modo de canal 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 entrantes user se reenvían como notifications/claude/channel
• las solicitudes de permiso de Claude recibidas mediante MCP se rastrean en memoria
• si la conversación vinculada envía más tarde yes abcde o no abcde, 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

Esto es intencionalmente específico del cliente. Los clientes MCP genéricos deben depender de las herramientas de sondeo estándar.

Configuración de cliente MCP

Ejemplo de configuración de cliente stdio:

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

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

Opciones

OmeniaClaw mcp serve admite:

Seguridad y límite de confianza

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

Eso significa:

• las listas de remitentes permitidos, el emparejamiento y la confianza a nivel de canal siguen perteneciendo a la configuración subyacente de canal de OmeniaClaw
• messages_send solo puede responder mediante 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 del Gateway en los que confiarías para cualquier otro cliente de Gateway remoto

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

Pruebas

OmeniaClaw incluye una prueba smoke determinista de Docker para este puente:

pnpm test:docker:mcp-channels

Esa prueba smoke:

• inicia un contenedor Gateway con datos iniciales
• inicia un segundo contenedor que ejecuta OmeniaClaw mcp serve
• verifica el descubrimiento de conversaciones, las lecturas de transcripciones, las lecturas de metadatos de adjuntos, el comportamiento de la cola de eventos en vivo y el enrutamiento de envíos salientes
• valida notificaciones de canal y permisos al estilo Claude mediante el puente MCP stdio real

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

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

Solución de problemas

OmeniaClaw como registro de cliente MCP

Esta es la ruta de OmeniaClaw mcp list, show, set y unset.

Estos comandos no exponen OmeniaClaw mediante MCP. Administran las definiciones de servidores MCP propiedad de OmeniaClaw bajo mcp.servers en la configuración de OmeniaClaw.

Esas definiciones guardadas son para runtimes que OmeniaClaw inicia o configura más tarde, como Pi integrado y otros adaptadores de runtime. OmeniaClaw almacena las definiciones de forma centralizada para que esos runtimes no tengan que mantener sus propias listas duplicadas de servidores MCP.

Los adaptadores de runtime pueden normalizar este registro compartido a la forma que espera su cliente descendente. Por ejemplo, Pi integrado consume directamente los valores transport de OmeniaClaw, mientras que Claude Code y Gemini reciben valores type nativos de CLI como http, sse o stdio.

Definiciones guardadas de servidores MCP

OmeniaClaw también almacena un registro ligero de servidores MCP en la configuración para superficies que quieren definiciones MCP administradas por OmeniaClaw.

Comandos:

• OmeniaClaw mcp list
• OmeniaClaw mcp show [name]
• OmeniaClaw mcp set <name> <json>
• OmeniaClaw mcp unset <name>

Notas:

• list ordena los nombres de los servidores.
• show sin un nombre imprime el objeto completo de servidores MCP configurados.
• set espera un valor de objeto JSON en la línea de comandos.
• Usa transport: "streamable-http" para servidores MCP Streamable HTTP. OmeniaClaw 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 indicado no existe.

Ejemplos:

OmeniaClaw mcp listOmeniaClaw mcp show context7 --jsonOmeniaClaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'OmeniaClaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'OmeniaClaw mcp unset context7

Forma de configuración de ejemplo:

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http"      }    }  }}

Transporte Stdio

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

Transporte SSE / HTTP

Se conecta a un servidor MCP remoto mediante HTTP Server-Sent Events.

Ejemplo:

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

Los valores sensibles en url (userinfo) y headers se redactan en los registros y la salida de estado.

Transporte Streamable HTTP

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

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

Ejemplo:

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

Límites actuales

Esta página documenta el puente tal como se entrega hoy.

Límites actuales:

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

Relacionado

• Referencia de CLI
• Plugins