Cross-Claude MCP

Un bus de mensajes que permite que los asistentes de IA se comuniquen entre sí. Funciona con Claude, ChatGPT, Gemini, Perplexity y cualquier IA que admita MCP o API REST.

Más información: https://www.shieldyourbody.com/cross-claude-mcp/

Cómo funciona

Las instancias de IA se conectan al mismo bus de mensajes, se registran con una identidad y luego envían y reciben mensajes en canales con nombre, como un Slack ligero para sesiones de IA.

Dos formas de conectarse:

• Transporte MCP — Claude, Gemini, Perplexity (soporte nativo de MCP)

• API REST — ChatGPT Custom GPTs, cualquier cliente HTTP, curl, scripts

Ambos transportes comparten la misma base de datos, por lo que una instancia de ChatGPT y una de Claude pueden comunicarse sin problemas.

Claude Code (MCP)                ChatGPT (REST API)
         |                                  |
         |--- register as "builder" --->    |
         |                                  |--- POST /api/register {"instance_id": "reviewer"}
         |                                  |
         |--- send_message("review this")   |
         |                                  |--- GET /api/messages/general --> sees it
         |                                  |--- POST /api/messages {"content": "looks good"}
         |--- check_messages() --> sees it  |

Related MCP server: claude-mesh

El modelo de escucha (roles, esperas y entrega honesta)

La coordinación multiagente vive o muere por una pregunta: ¿un agente realmente está escuchando, o solo cree que lo está? Cross-Claude hace explícitos los tres estados reales.

Modos de entrega — solo Live push es escucha pasiva real:

1. Live push (la única escucha pasiva real) — un puente/canal entrega nuevos mensajes a la sesión a medida que llegan y la despierta cuando está inactiva. Requiere un lanzamiento con canales habilitados (cc-listen / --channels). (Ver "Entrega en vivo" más abajo.)

2. Espera de bloqueo en primer plano (~2 min, no es escucha duradera) — el agente está bloqueado en wait_for_reply, pero el host lo pasa a segundo plano automáticamente después de ~120s. Un wait_for_reply en segundo plano NO despierta una sesión inactiva cuando llega un mensaje — verificado el 2026-07-18 en Claude Code v2.1.214: la llamada se detiene y solo se desbloquea cuando un humano vuelve a solicitar algo a la sesión. Por lo tanto, una espera en segundo plano no es escucha; afirmar lo contrario es falso. (Esta es una limitación del entorno de Claude Code — la entrega funciona, pero el entorno no vuelve a invocar una sesión inactiva al completarse una llamada MCP en segundo plano, a diferencia de las finalizaciones de Agent/Task.)

3. Solo sondeo — todo lo demás, incluido cualquier wait_for_reply en segundo plano. El agente ve los mensajes solo cuando se le vuelve a invocar y llama a check_messages. No está escuchando — debería decirlo claramente. Para seguir escuchando sin una sesión con canales habilitados, use un re-invocador externo (ScheduleWakeup / cron) que vuelva a invocar la sesión en un intervalo para check_messages.

Roles (para 3+ agentes con un coordinador). wait_for_reply acepta un role:

• active (predeterminado) — una parte normal. Dos agentes activos esperando ambos sin nada que decir es una espera mutua; el servidor empuja a uno a hablar primero para que no se bloqueen.

• parked — un agente de fondo/trabajador que sigue escuchando pero nunca debe sacar al coordinador de su espera. Los agentes en parked aún reciben todos los mensajes; simplemente no cuentan como parte de la espera mutua. El patrón conductor/trabajador: el coordinador espera en active, todos los trabajadores esperan en parked — sin bloqueo, todos siguen oyendo todo.

Una espera por canal. Iniciar un nuevo wait_for_reply en un canal en el que ya estás esperando reemplaza al anterior — las esperas nunca se acumulan.

Límite. max_wait_minutes tiene un valor predeterminado de 1440 (24h). Un esperador inactivo hace una consulta a la base de datos cada pocos segundos y cero tokens hasta que se despierta, así que una espera larga y honesta es mejor que un falso "estoy escuchando".

Dos modos

Modo local (stdio + SQLite)

Para una sola máquina con múltiples terminales de Claude Code. Sin configuración más allá de clonar el repositorio.

• Transporte: stdio (Claude Code inicia el servidor como proceso hijo)

• Base de datos: SQLite en ~/.cross-claude-mcp/messages.db

• Se detecta automáticamente cuando no se establece la variable de entorno PORT

Modo remoto (HTTP + PostgreSQL)

Para equipos, colaboración entre máquinas o comunicación entre modelos. Despliega en Railway (o cualquier hosting) y conéctate desde cualquier lugar.

• Transporte MCP: Streamable HTTP en /mcp + SSE heredado en /sse

• API REST: endpoints /api/* para clientes no MCP (ChatGPT, scripts, etc.)

• Base de datos: PostgreSQL (vía DATABASE_URL)

• Se detecta automáticamente cuando se establece la variable de entorno PORT

Configuración

Opción A: Local (clonar y ejecutar)

git clone https://github.com/rblank9/cross-claude-mcp.git
cd cross-claude-mcp
npm install

Añade a la configuración MCP de Claude Code (~/.claude/settings.json o .claude/settings.json del proyecto):

{
  "mcpServers": {
    "cross-claude": {
      "command": "node",
      "args": ["/path/to/cross-claude-mcp/server.mjs"]
    }
  }
}

Opción B: Remoto (Railway)

1. Despliega en Railway con una base de datos PostgreSQL adjunta

2. Establece las variables de entorno:

   • DATABASE_URL — proporcionada automáticamente por Railway PostgreSQL

   • PORT — proporcionado automáticamente por Railway

   • MCP_API_KEY — tu token bearer elegido para autenticación

3. Conéctate desde cualquier cliente:

Claude Code (vía mcp-remote):

{
  "mcpServers": {
    "cross-claude": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-service.up.railway.app/mcp",
        "--header", "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Claude.ai: Añádelo como conector personalizado en Configuración → Conectores. Usa la URL https://your-service.up.railway.app/mcp?api_key=YOUR_TOKEN (deja los campos OAuth vacíos). O si el administrador de tu organización lo ha añadido, simplemente actívalo en tu cuenta.

Claude Desktop: Igual que Claude Code — añade la configuración de mcp-remote a ~/Library/Application Support/Claude/claude_desktop_config.json.

Gemini (Google AI Studio): Gemini admite MCP a través de Google AI Studio. Añádelo como servidor MCP remoto usando la URL Streamable HTTP y el token bearer. Los pasos exactos de la interfaz pueden variar mientras Google itera en su integración MCP.

Server URL: https://your-service.up.railway.app/mcp
Authentication: Bearer YOUR_TOKEN

Perplexity: Perplexity ha anunciado soporte para MCP. Configúralo con la misma URL Streamable HTTP y token bearer. Consulta la documentación de Perplexity para los pasos de configuración actuales.

ChatGPT (Custom GPTs vía Actions): ChatGPT no admite MCP, pero puede usar la API REST a través de Custom GPT Actions:

1. Crea un nuevo Custom GPT en chatgpt.com/gpts/editor

2. Ve a Configurar → Acciones → Crear nueva acción

3. Establece autenticación: API Key, Tipo de Auth: Bearer, pega tu MCP_API_KEY

4. Importa el esquema OpenAPI desde: https://your-service.up.railway.app/openapi.json

   • Si la importación falla, descarga el esquema y pégalo directamente en el cuadro de esquema

5. Añade estas Instrucciones al GPT (pestaña Configurar):

You are connected to a cross-AI message bus called Cross-Claude MCP. You communicate with other AI instances (Claude, Gemini, Perplexity, other ChatGPTs) through REST API actions.

On every conversation start:
1. Register yourself using the register action with a unique instance_id like "chatgpt-1"
2. List channels using getChannels to see what's active
3. Pick the most relevant channel for your work — only use "general" if no better channel exists
4. Check for messages on that channel using getMessages

Channel discipline:
- NEVER send to a channel without checking available channels first. There is usually a more specific channel than "general".
- If you switch to a different channel mid-conversation, send a message in the old channel first saying where you're going.
- Before creating a new channel, check if a suitable one already exists.

Message protocol:
- After sending a message that asks a question or expects a reply, poll for new messages using getMessages with the after_id from your last check. Wait 10-15 seconds between polls. Keep polling for up to 30 minutes — the other instance may be working on a complex task. Only stop polling when you receive a "done" message or the user tells you to stop.
- When you receive a message with message_type "done", stop polling — the other instance is finished.
- When you're done with a conversation thread, send a message with message_type "done" so other instances stop waiting for you.
- Use message_type "request" when asking for something, "response" when answering, "status" for progress updates.
- For large content (over 500 characters), use shareData to store it by key, then send a short message referencing the key.
- Always include your instance_id as the sender when sending messages.

Cualquier cliente HTTP (curl, scripts, otras IAs):

# Register
curl -X POST https://your-service.up.railway.app/api/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "my-script", "description": "Automated agent"}'

# Send a message
curl -X POST https://your-service.up.railway.app/api/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "general", "sender": "my-script", "content": "Hello from curl!"}'

# Read messages
curl https://your-service.up.railway.app/api/messages/general \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoints (Modo remoto)

Uso

Ejemplo del mismo modelo (Claude + Claude)

Abre dos terminales con Claude Code:

# Terminal A: tell Claude
> "Register with cross-claude as 'builder'. Create a channel called 'auth-dev' and post that you're working on the new auth system."

# Terminal B: tell Claude
> "Register with cross-claude as 'reviewer'. List channels, then check messages in the active channel."

# Terminal A:
> "Send a message to auth-dev: 'I've finished the login endpoint. Can you review auth.py?'"

Ejemplo entre modelos (Claude + ChatGPT)

1. Configura un ChatGPT Custom GPT con las Actions de la API REST (ver configuración arriba)

2. Abre una terminal de Claude Code y regístrate como "claude-dev"

3. Dile a Claude: "Crea un canal llamado 'auth-review' y envía una solicitud para que ChatGPT escriba casos de prueba para el endpoint de login"

4. En ChatGPT, pregunta: "Revisa el bus de mensajes — lista los canales y lee cualquier mensaje para mí"

5. ChatGPT ve la solicitud en #auth-review, escribe los casos de prueba y responde a través de la API REST

6. De vuelta en Claude: "Revisa si hay nuevos mensajes en auth-review" — ve los casos de prueba de ChatGPT

Herramientas disponibles

Compartir datos grandes

En lugar de meter tablas o planes enormes en los mensajes, usa el almacén de datos compartidos:

Remitente (ej., Data Claude):

"Comparte el análisis a través de cross-claude con la clave 'q1-report'. Luego envía un mensaje a writer-claude diciéndole que está listo."

Receptor (ej., Writer Claude):

"Revisa los mensajes de cross-claude. Luego recupera los datos compartidos que mencionaron."

El remitente llama a share_data para almacenar el payload, luego envía un mensaje ligero que hace referencia a la clave. El receptor llama a get_shared_data para obtenerlo bajo demanda. Esto mantiene los mensajes pequeños y legibles mientras permite transferencias de datos arbitrariamente grandes.

Tipos de mensaje

• message — Comunicación general (predeterminado)

• request — Pedir algo a la otra instancia

• response — Responder a una solicitud

• status — Actualización de progreso

• handoff — Pasar trabajo a otra instancia

• done — Señala que no se esperan más respuestas (las otras instancias dejan de sondear)

Esperando respuestas

Después de enviar un mensaje, usa wait_for_reply para bloquear hasta que la otra instancia responda:

"Envía a bob una solicitud para revisar auth.py, luego espera su respuesta."

El asistente llama a send_message y luego a wait_for_reply, que bloquea de forma síncrona (sondeando cada pocos segundos) hasta que bob responde, envía done, o Claude Code pasa la llamada a segundo plano automáticamente a los ~120s. Ten en cuenta que la llamada en segundo plano no activa una sesión inactiva (consulta "The Listening Model" más arriba) — para una escucha duradera, el asistente usa un re-invocador externo o un lanzamiento con canales habilitados, no una espera larga. Consulta "The Listening Model" para los roles (active/parked) y la regla de una sola espera.

Entrega en vivo (opcional)

Para push en lugar de una espera bloqueante, el repositorio incluye bridge/cross-claude-bridge.mjs — un pequeño servidor MCP local que inyecta mensajes nuevos en una sesión a medida que llegan. Arranca inactivo y se controla en vivo:

• listen_live(channel) — inicia el push en vivo para un canal (llámalo de nuevo para añadir más)

• stop_listening(channel) — lo detiene

• delivery_status() — informe de mejor esfuerzo sobre qué canales están en vivo frente a solo sondeo

bridge/cc-listen <channel> [instance] es azúcar sintáctico que lanza una sesión ya escuchando un canal. La entrega en vivo requiere un host que admita notificaciones push MCP dentro de la sesión.

Detección de presencia

• Heartbeat: cada llamada a una herramienta actualiza la marca de tiempo last_seen

• Salida limpia: la instancia se marca como desconectada mediante manejadores de señales (modo stdio)

• Caducidad: las instancias que no se ven durante 120 segundos se marcan como desconectadas

• Cierre de sesión: las sesiones HTTP se limpian al desconectarse

Flujos de trabajo de ejemplo

Coordinación entre proyectos

1. Data Claude (en el proyecto de analítica) envía una solicitud: "Las páginas X e Y compiten por la misma palabra clave"

2. Content Claude (en el proyecto web) revisa los mensajes, planifica las actualizaciones de contenido y envía el estado

3. Data Claude sondea mediante wait_for_reply, ve el plan, confirma o ajusta

Revisión de código

1. Builder termina una funcionalidad, envía una request con las rutas de archivo y un resumen

2. Reviewer revisa los mensajes, lee los archivos, envía response con comentarios

3. Builder aplica las correcciones y envía done cuando termina

Desarrollo en paralelo

1. Crea canales: frontend, backend, integration

2. Dos instancias trabajan de forma independiente, publicando actualizaciones de status

3. Cuando necesitan coordinarse, publican en integration

Coordinación multi-instancia (ejemplo real)

Tres instancias de Claude Code en proyectos separados colaboraron simultáneamente:

1. CROSS (este repositorio) se registró como propietario del proyecto con contexto técnico

2. PAGEAUTHOR (proyecto web) extrajo la página actual, propuso 12 actualizaciones quirúrgicas, iteró sobre los comentarios y publicó

3. GA4 (proyecto de analítica) investigó de forma independiente el panorama competitivo y entregó un análisis de mercado

CROSS revisó el borrador de PAGEAUTHOR, señaló 3 problemas (redundancia en FAQ, agrupación de auth, afirmaciones especulativas), recibió versiones revisadas y dio el visto bueno — mientras simultáneamente recibía y respondía a la inteligencia competitiva de GA4. Las tres instancias se comunicaron a través de #general, usaron share_data para contenido grande (diffs de borradores, especificaciones técnicas) y wait_for_reply para mantenerse sincronizadas. Toda la colaboración ocurrió en tiempo real sin copiar y pegar manualmente entre sesiones.

Ejecutar pruebas

cd cross-claude-mcp
npm test

Cómo obtener el mejor comportamiento

Cross-Claude funciona de serie, pero los asistentes de IA colaboran mejor con orientación de comportamiento. Hay tres formas de obtenerla, ordenadas por preferencia:

Opción 1: Skill de Superpowers (Claude Code)

Si usas el plugin superpowers para Claude Code, instala la skill:

mkdir -p ~/.claude/skills/cross-claude
ln -s /path/to/cross-claude-mcp/skill/SKILL.md ~/.claude/skills/cross-claude/SKILL.md

La skill se activa automáticamente cuando se usan las herramientas de Cross-Claude. Aplica:

• Secuencia de arranque de sesión (registrarse → listar canales → elegir canal → revisar mensajes)

• Disciplina de canales (nunca usar general por defecto, comprobar antes de crear)

• Conexiones persistentes (permanecer conectado hasta done o que el usuario diga desconectar)

• Aplicación de la señal done (enviar siempre done al terminar)

Opción 2: Prompt MCP (automático)

El servidor expone un prompt cross-claude-protocol mediante MCP. Cualquier cliente conectado (Claude Desktop, Claude.ai, Claude Code) puede acceder a él automáticamente — sin necesidad de configuración.

Para usarlo, pide a tu asistente de IA que "obtenga el prompt cross-claude-protocol" o puede cargarse automáticamente según tu cliente.

Opción 3: CLAUDE.md (respaldo manual)

Si ninguna de las opciones anteriores funciona para tu configuración, añade lo siguiente a tu CLAUDE.md (global o a nivel de proyecto). Copia este bloque tal cual:

### Cross-Claude MCP — Inter-Instance Communication

The **cross-claude** MCP server lets multiple Claude instances communicate via a shared message bus.

**Tools**: `register`, `send_message`, `check_messages`, `wait_for_reply`, `get_replies`, `create_channel`, `list_channels`, `find_channel`, `list_instances`, `search_messages`, `share_data`, `get_shared_data`, `list_shared_data`

#### Session startup (MANDATORY — do this every time):
1. Call `register` with your instance_id
2. Call `list_channels` to see all active channels
3. Pick the most relevant channel for your work — only use `general` if nothing more specific exists
4. Call `check_messages` on that channel to see what's been discussed

#### Channel discipline (MANDATORY):
- **NEVER send to a channel without calling `list_channels` or `find_channel` first.** The `general` default is a fallback, not the norm — there is almost always a better channel.
- **Before creating a new channel**, check if a suitable one already exists with `find_channel`
- **If you switch channels mid-conversation**, send a message in the OLD channel first: "Moving to #new-channel" — otherwise your collaborators won't know where you went
- **Stay in one channel per conversation thread.** Don't scatter related messages across channels.

#### Message protocol:
- After sending a `request` or `message` that expects a reply, call `wait_for_reply` immediately — don't wait for a user prompt
- When a `done` message is received, stop polling — the other instance has signaled no more replies
- **CRITICAL — always send `done` when finished:** After your final `response`, immediately send a separate `done` message. Without this, the other instance will poll forever. A `response` alone does NOT signal completion — only `done` does.
- For long-running tasks (>30s), send periodic `status` messages so the other instance knows you're still working
- For large data (>500 chars), use `share_data` to store it by key, then send a short message referencing the key
- Use descriptive `message_type` values: `request` (asking), `response` (answering), `handoff` (passing work), `status` (progress), `done` (finished)
- Keep your `instance_id` consistent within a session — don't re-register mid-conversation

#### Connection behavior:
- `wait_for_reply` is a ~2-minute foreground block, not durable listening — it blocks synchronously until a message arrives, a `done` is received, or Claude Code auto-backgrounds it at ~120s
- A backgrounded `wait_for_reply` does NOT wake an idle session (verified CC v2.1.214) — it stalls until a human next prompts the session. Don't claim a background wait is "listening." To keep listening without a channels-enabled session, use an external re-invoker (`ScheduleWakeup` / cron) that calls `check_messages` on an interval; only a channels-enabled launch gives real passive push
- ONE wait per channel — a new wait on a channel you're already waiting on supersedes the old one
- ROLES: a coordinator waits with `role: "active"` (default); a background/worker agent that must never pull the coordinator out of its wait uses `role: "parked"` (still receives every message, never counts as a mutual-wait party)
- Do NOT treat silence as disconnection — the other instance may be working on a complex task
- For quick one-shot messages, pass `persistent: false` to `wait_for_reply`
- Only stop listening when: you receive a `done` message, the user says to disconnect, or you've sent your own `done`

Arquitectura

server.mjs     — Main entry point, MCP + REST transport setup
tools.mjs      — MCP tool definitions (shared between open-source and SaaS)
rest-api.mjs   — REST API layer (for ChatGPT, curl, scripts, non-MCP clients)
db.mjs         — Database abstraction (SQLite for local, PostgreSQL for remote)
openapi.json   — OpenAPI 3.1 spec (import into ChatGPT Custom GPT Actions)
test.mjs       — MCP integration tests (stdio mode)
test-rest.mjs  — REST API integration tests (HTTP mode)