kje-mcp

Servidor MCP compatible con Claude.ai que envuelve a Jim Brain (memoria persistente + estado del imperio + bóveda) y un despachador de Claude Code sin interfaz gráfica en el VPS de RackNerd, para que cualquier sesión web de Claude.ai pueda:

• leer el estado actual del imperio, los proyectos y las memorias recientes,

• buscar en la memoria semántica y en la bóveda de credenciales,

• escribir registros rápidos y memorias semánticas de vuelta a Brain,

• enviar sesiones de compilación claude -p en el VPS.

El servidor utiliza MCP Streamable HTTP (el transporte que espera la interfaz de "Conector personalizado" de Claude.ai). Utiliza el modo sin estado / respuesta JSON, por lo que puede ejecutarse en cualquier lugar donde pueda hacerlo una API HTTP normal, en este caso, Railway.

Herramientas expuestas

Todas las herramientas se autentican en Brain con el encabezado en minúsculas x-brain-key (el único encabezado que acepta Brain, grabado en la depuración de BridgeDeck del 27-04-2026). La capa MCP en sí acepta un token Bearer en el encabezado Authorization, que es lo que envía la interfaz de conector de Claude.ai.

Diseño de archivos

kje-mcp/
├── main.py                       # FastAPI + FastMCP server (deployed to Railway)
├── requirements.txt
├── railway.toml
├── .env.example
├── README.md
└── vps/
    ├── cc_dispatch_server.py     # Companion dispatcher — runs on the RackNerd VPS
    ├── requirements.txt
    └── kje-cc-dispatch.service   # systemd unit

1. Desplegar kje-mcp en Railway

1a. Enviar el repositorio a GitHub

cd C:\Users\Jim\Documents\GitHub\kje-mcp
git add .
git commit -m "feat: kje-mcp v1.0.0 — Claude.ai MCP wrapper for Jim Brain + CC dispatch"
gh repo create jharriGH/kje-mcp --public --source=. --remote=origin --push

1b. Crear el servicio de Railway

# from inside the kje-mcp dir
railway init                         # name it: kje-mcp
railway link                         # link to the new project
railway up                           # builds + deploys

O a través del panel de control: New Project → Deploy from GitHub Repo → jharriGH/kje-mcp. Railway detecta automáticamente Nixpacks Python y utiliza el startCommand de railway.toml.

1c. Configurar variables de entorno

railway variables --set BRAIN_KEY=jim-brain-kje-2026-kingjames
railway variables --set BRAIN_URL=https://jim-brain-production.up.railway.app
railway variables --set MCP_AUTH_KEY=jim-brain-kje-2026-kingjames

# OPTIONAL — only set these once the VPS dispatcher is up (step 2):
# railway variables --set VPS_DISPATCH_URL=https://cc.kj.empire/dispatch
# railway variables --set VPS_DISPATCH_KEY=<long-random-string>

Según la REGLA DE AUTOMATIZACIÓN DE VARIABLES DE ENTORNO, Claude Code gestiona esto; Jim nunca hace clic en los paneles de control de Railway.

1d. Verificar el despliegue

# replace <host> with the Railway-assigned URL (railway domain or your custom one)
curl -s https://<host>/health | jq
# expect: {"status":"ok","service":"kje-mcp",...,"vps_dispatch_configured":false,...}

# initialize handshake (Claude.ai will send the same)
curl -s -X POST https://<host>/mcp/ \
  -H "Authorization: Bearer jim-brain-kje-2026-kingjames" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' | jq

# list tools
curl -s -X POST https://<host>/mcp/ \
  -H "Authorization: Bearer jim-brain-kje-2026-kingjames" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools[].name'
# expect 7 names: brain_status, brain_search, brain_get_project, brain_vault_search,
#                 brain_log, brain_memory, cc_dispatch

2. Conectar desde la web de Claude.ai

1. Abre claude.ai → Settings → Connectors → Add custom connector.

2. Nombre: KJE MCP.

3. URL: https://<tu-host-de-railway>/mcp/ (ten en cuenta la barra diagonal final y la ruta /mcp/).

4. Autenticación: API key / Bearer token → pega jim-brain-kje-2026-kingjames (o lo que hayas configurado en MCP_AUTH_KEY).

5. Guardar. Claude.ai realiza el protocolo de enlace initialize + tools/list de MCP; si aparece la marca de verificación verde junto a "KJE MCP", las 7 herramientas estarán disponibles en el chat.

En cualquier conversación nueva de Claude.ai:

• Abre el menú de herramientas/conectores de la conversación y activa KJE MCP.

• Comienza tu prompt con el equivalente a brain_session_start:

  "Usa KJE MCP. Llama a brain_status y brain_get_project para kj_codedeck (depth=standard) antes de responder. Luego [tarea]."

Cuando termines, Claude.ai ejecutará el ritual de cierre a través del mismo conector: brain_memory para el resumen, brain_log para el progreso y cc_dispatch si es necesario seguir trabajando en el VPS.

3. (Opcional) Configurar el despachador VPS para cc_dispatch

Sin esto, cc_dispatch devuelve un error limpio cc_dispatch_not_configured y las otras seis herramientas funcionan bien. Configúralo cuando realmente quieras que Claude.ai inicie sesiones de CC en el VPS.

3a. Sincronizar la carpeta vps/ en 104.223.120.21

# from your laptop, in the kje-mcp repo
scp -r vps/ jim@104.223.120.21:/home/jim/kje-mcp/

3b. Crear un venv e instalar dependencias en el VPS

ssh jim@104.223.120.21
cd /home/jim/kje-mcp
python3 -m venv .venv
.venv/bin/pip install -r vps/requirements.txt

3c. Configurar .env

cat > /home/jim/kje-mcp/vps/.env <<'EOF'
VPS_DISPATCH_KEY=<long-random-string-paste-same-on-railway>
BRAIN_URL=https://jim-brain-production.up.railway.app
BRAIN_KEY=jim-brain-kje-2026-kingjames
PROJECT_REPOS_BASE=/home/jim/repos
# Optional overrides for slugs whose repo dir name differs from the slug:
# PROJECT_REPOS_OVERRIDES={"kj_autonomous":"/home/jim/n8n-canvas/kj-autonomous"}
CLAUDE_BIN=/usr/local/bin/claude
DISPATCH_LOG_DIR=/var/log/kje-cc-sessions
EOF

sudo mkdir -p /var/log/kje-cc-sessions
sudo chown jim:jim /var/log/kje-cc-sessions

3d. Instalar + iniciar la unidad de systemd

sudo cp /home/jim/kje-mcp/vps/kje-cc-dispatch.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now kje-cc-dispatch
sudo systemctl status kje-cc-dispatch
curl -s http://127.0.0.1:8088/health

3e. Exponer con TLS (nginx + Let's Encrypt)

# /etc/nginx/sites-available/cc.kj.empire
server {
    listen 443 ssl http2;
    server_name cc.kj.empire;

    ssl_certificate     /etc/letsencrypt/live/cc.kj.empire/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cc.kj.empire/privkey.pem;

    client_max_body_size 4m;
    proxy_read_timeout   65s;

    location /dispatch {
        proxy_pass         http://127.0.0.1:8088/dispatch;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Dispatch-Key $http_x_dispatch_key;
    }

    location /health {
        proxy_pass http://127.0.0.1:8088/health;
    }
}

sudo ln -s /etc/nginx/sites-available/cc.kj.empire /etc/nginx/sites-enabled/
sudo certbot --nginx -d cc.kj.empire
sudo nginx -t && sudo systemctl reload nginx

3f. Conectar el servicio kje-mcp a él

# from the kje-mcp repo on your laptop
railway variables --set VPS_DISPATCH_URL=https://cc.kj.empire/dispatch
railway variables --set VPS_DISPATCH_KEY=<same-random-string>
railway redeploy

/health en el servicio kje-mcp ahora debería mostrar "vps_dispatch_configured": true.

Cómo utiliza esto una sesión de Claude.ai de principio a fin

1. Inicio de sesión. Conector activado. Claude.ai llama a brain_status → contexto del imperio, luego brain_get_project("kj_codedeck", "standard") → prompt de inyección.

2. Trabajando. Claude.ai responde desde el razonamiento en el chat. A mitad del proceso, llama a brain_search para decisiones previas o brain_vault_search para credenciales que necesita discutir.

3. Trabajo pesado. Cuando el trabajo requiere una sesión de compilación CC real, Claude.ai llama a cc_dispatch(project="kj_codedeck", prompt="<prompt completo de compilación>"). El despachador del VPS responde inmediatamente con un session_id. La sesión de CC se ejecuta en segundo plano.

4. Transferencia. Cuando termina la sesión de CC, el despachador del VPS publica una transferencia a Brain /codedeck/handoff (registro rápido + actualización de next_action del proyecto + tarjeta de compilación si se tocaron más de 3 archivos + memoria semántica en cola). La siguiente sesión de Claude.ai lo ve a través de brain_search.

5. Ritual de cierre. Claude.ai llama a brain_memory (resumen completo), brain_log (evento de progreso), y el guardado de la tarjeta de compilación ocurre automáticamente en el lado del servidor a través de la transferencia. No le preguntes a Jim "¿qué opción?", esa es la regla.