Servidor MCP

La forma más potente de usar Karajan Code es como servidor MCP dentro de tu agente de IA. En lugar de alternar entre terminales y copiar/pegar outputs, tu agente envía tareas directamente a kj_run y recibe resultados estructurados, todo dentro de la conversación.

En la práctica, desde tu agente

Una de esas herramientas MCP es la memoria del proyecto: kj_rag_query. Antes de suponer qué hace el código, tu agente puede preguntarle al índice, y obtener una respuesta anclada en tu código, tus documentos y tus planes reales, no una adivinanza. Una política de sensibilidad decide qué modelo puede ver qué, y los secretos quedan excluidos del índice, así que la memoria ayuda sin filtrar nada. Tú no ejecutas nada: la herramienta está ahí en la sesión, y un buen agente la usa en vez de hacer grep a ciegas.

Bajo el capó, pruébalo tú mismo

Esa misma memoria es un CLI, así que puedes consultarla directamente:

kj rag index                       # construye (o refresca) el índice de este repo
kj rag query "¿dónde se define la stage de pre-loop?"   # una respuesta anclada, con fuentes

Reindexa tras un cambio (kj rag index --since <ref>) y las respuestas siguen al código. Nada sensible se embebe, el índice se construye con la política de sensibilidad aplicada.

Auto-registro

Tras npm install -g karajan-code, el servidor MCP se registra automáticamente en Claude Code y Codex. No requiere configuración manual.

El hook de postinstall escribe la configuración del servidor en:

• Claude Code: ~/.claude.json bajo mcpServers
• Codex: ~/.codex/config.toml bajo mcp_servers

El registro es idempotente, se puede ejecutar múltiples veces sin problemas.

Tras actualizar: Transport closed

Si actualizas Karajan Code mientras la sesion de tu host MCP sigue abierta, el proceso actual de karajan-mcp puede cerrarse y el host mostrar Transport closed.

Esto es esperado: desde v1.57.0, Karajan MCP realiza un reinicio graceful tras actualizaciones npm. El servidor escribe un marcador de reinicio y sale limpiamente. La nueva instancia detecta el marcador y arranca con codigo fresco.

Recuperación rápida:

1. Reinicia la sesión del host MCP (Claude/Codex).
2. Confirma que el servidor aparece listado (codex mcp list o equivalente en tu host).
3. Ejecuta kj_config (y opcionalmente un kj_plan corto) antes de tareas largas.

Configuración manual

Si el auto-registro no funciona o necesitas rutas personalizadas:

Claude Code

Añadir a ~/.claude.json:

{
  "mcpServers": {
    "karajan-mcp": {
      "type": "stdio",
      "command": "karajan-mcp"
    }
  }
}

Codex

Añadir a ~/.codex/config.toml:

[mcp_servers."karajan-mcp"]
command = "karajan-mcp"

Host MCP custom

Iniciar el servidor vía stdio:

karajan-mcp

O con una ruta explícita:

node /path/to/karajan-code/src/mcp/server.js

Herramientas disponibles

Karajan Code expone 27 herramientas MCP:

Herramienta	Params requeridos	Descripción
kj_run	task	Ejecutar el pipeline completo coder → sonar → reviewer
kj_discover	task	Detección de gaps pre-ejecución con 5 modos (gaps, momtest, wendel, classify, jtbd)
kj_code	task	Modo solo coder (sin revisión)
kj_review	task	Modo solo reviewer sobre el diff actual
kj_plan	task	Generar plan de implementación con telemetría heartbeat/stall
kj_resume	sessionId	Reanudar una sesión pausada, detenida o fallida
kj_preflight	humanResponse	El humano confirma la config de agentes antes de kj_run/kj_code
kj_agents	,	Listar o cambiar agente IA por rol (scope sesión/proyecto/global)
kj_status	,	Dashboard con estados de HUs, stage actual, tiempos, progreso. Devuelve JSON estructurado
kj_report	,	Leer informes de sesión con desglose de costes
kj_scan	,	Ejecutar escaneo SonarQube en el proyecto actual
kj_init	,	Inicializar config, reglas de revisión, SonarQube y scaffolding de BecarIA (--scaffold-becaria)
kj_doctor	,	Verificar dependencias del sistema y CLIs de agentes
kj_config	,	Mostrar configuración actual
kj_roles	,	Listar roles del pipeline o mostrar templates de roles
kj_triage	task	Clasificar complejidad de tareas y activar roles
kj_researcher	task	Investigar contexto del codebase
kj_architect	task	Diseñar arquitectura de la solución
kj_board	action	Start/stop/status del dashboard HU Board
kj_hu	action	Gestionar historias de usuario (crear, actualizar, listar, obtener) en el HU Board local
kj_suggest	observation	Enviar una observación a Solomon sin interrumpir el pipeline
kj_skills	,	Listar, instalar o eliminar skills especificos de dominio para los roles del pipeline
kj_undo	,	Revertir la ultima ejecucion del pipeline (soft reset o hard)

Ver la Referencia de Herramientas MCP para la documentación completa de parámetros.

Usar kj_run

kj_run es la herramienta principal. Orquesta el pipeline completo y devuelve resultados estructurados.

Uso básico

Desde tu agente de IA, simplemente pide:

“Usa kj_run para añadir validación de inputs al formulario de registro”

El agente llama:

{
  "tool": "kj_run",
  "params": {
    "task": "Añadir validación de inputs al formulario de registro"
  }
}

Con opciones

{
  "tool": "kj_run",
  "params": {
    "task": "Corregir la vulnerabilidad de inyección SQL en búsqueda",
    "coder": "claude",
    "reviewer": "codex",
    "mode": "paranoid",
    "methodology": "tdd",
    "maxIterations": 5,
    "autoCommit": true
  }
}

Con BecarIA Gateway

{
  "tool": "kj_run",
  "params": {
    "task": "Añadir validación de inputs al formulario de registro",
    "enableBecaria": true
  }
}

Cuando enableBecaria es true, Karajan crea una PR en borrador tras la primera iteración del coder y todos los agentes (Coder, Reviewer, Sonar, Solomon, Tester, Security, Planner) publican sus resultados como comentarios/reviews en la PR. Los dispatch events configurables disparan workflows de GitHub Actions en cada etapa del pipeline.

Con integración Planning Game

{
  "tool": "kj_run",
  "params": {
    "task": "Implementar autenticación de usuarios",
    "pgTask": "PRJ-TSK-0042",
    "pgProject": "MiProyecto"
  }
}

La herramienta obtiene el contexto completo de la card (descripción, criterios de aceptación) desde Planning Game.

Progreso en tiempo real

Durante la ejecución, Karajan envía notificaciones de progreso en tiempo real vía logging MCP. Tu agente ve actualizaciones a medida que cada etapa se completa:

[1] coder:start, Escribiendo código y tests...
[1] coder:end, Generación de código completada
[1] sonar:start, Ejecutando análisis SonarQube...
[1] sonar:end, Quality gate superado
[1] reviewer:start, Revisando código...
[1] reviewer:end, APROBADO
[1] session:end, Pipeline completado

Las etapas de progreso incluyen: session:start, iteration:start, planner:start/end, coder:start/end, refactorer:start/end, tdd:result, sonar:start/end, reviewer:start/end, iteration:end, solomon:escalate, question, session:end, pipeline:tracker.

Tracker acumulativo del pipeline

Además de los eventos individuales de stage, Karajan emite un evento pipeline:tracker tras cada transición de stage con el estado acumulativo completo:

{
  "type": "pipeline:tracker",
  "detail": {
    "stages": [
      { "name": "triage", "status": "done", "summary": "medium" },
      { "name": "coder", "status": "running", "summary": "claude/sonnet" },
      { "name": "sonar", "status": "pending" },
      { "name": "reviewer", "status": "pending" }
    ]
  }
}

Esto permite a los hosts MCP renderizar un único widget de progreso mostrando todas las stages de un vistazo, en lugar de interpretar eventos individuales.

Para herramientas single-agent (kj_code, kj_review, kj_plan), también se emiten logs de tracker start/end via sendLoggingMessage.

Formato de respuesta

Ejecución exitosa

{
  "ok": true,
  "sessionId": "s_2026-02-28T20-47-24-270Z",
  "approved": true,
  "review": {
    "status": "approved",
    "summary": "El código cumple todos los estándares",
    "issues": [],
    "suggestions": ["Considerar extraer la validación a un helper"]
  },
  "git": {
    "committed": true,
    "commits": ["abc123"],
    "branch": "feat/signup-validation",
    "pushed": false
  }
}

Sesión pausada

Cuando la detección fail-fast se activa o se necesita clarificación:

{
  "ok": false,
  "paused": true,
  "sessionId": "s_2026-02-28T20-47-24-270Z",
  "question": "El reviewer rechazó el mismo issue dos veces. ¿Procedemos?",
  "context": "reviewer_fail_fast"
}

Reanudar con kj_resume:

{
  "tool": "kj_resume",
  "params": {
    "sessionId": "s_2026-02-28T20-47-24-270Z",
    "answer": "Sí, proceder con el enfoque actual"
  }
}

Respuesta de error

{
  "ok": false,
  "error": "SonarQube no es accesible",
  "tool": "kj_run",
  "category": "sonar_unavailable",
  "suggestion": "Intenta: docker start sonarqube, o usa noSonar: true"
}

Categorías de error: sonar_unavailable, auth_error, config_error, agent_missing, timeout, git_error.

Gestión de sesiones

Las sesiones persisten en disco en $KJ_HOME/sessions/{sessionId}/. Esto permite:

• Pausar/reanudar entre conversaciones del agente
• Tracking de costes por sesión con kj_report
• Auto-limpieza de sesiones más antiguas que session.expiry_days (por defecto: 30)

Listar sesiones

{
  "tool": "kj_report",
  "params": { "list": true }
}

Desglose de costes

{
  "tool": "kj_report",
  "params": {
    "sessionId": "s_2026-02-28T20-47-24-270Z",
    "trace": true,
    "currency": "usd"
  }
}

Devuelve un desglose etapa por etapa con tiempos, tokens y costes.

MCPs complementarios

Karajan Code funciona bien junto a otros servidores MCP:

MCP	Cómo complementa a Karajan
Planning Game	Gestión de tareas, obtener tareas, actualizar estados, seguir sprints (servidor MCP)
GitHub	Creación de PRs, gestión de issues, checks de CI/CD
Chrome DevTools	Verificación visual de cambios de UI tras la codificación
SonarQube	Acceso directo a informes de calidad (Karajan tiene SonarQube integrado, pero el MCP añade consulta directa)

Ejemplo de workflow con Planning Game

1. El agente obtiene la tarea de mayor prioridad desde Planning Game MCP
2. El agente envía la tarea a kj_run
3. Karajan orquesta coder → sonar → reviewer
4. El agente actualiza el estado de la card a “To Validate” en Planning Game
5. El agente crea una PR vía GitHub MCP

Todo dentro de una única conversación, totalmente automatizado.

Solución de problemas

Problema	Solución
Servidor MCP no encontrado	Ejecutar npm install -g karajan-code para activar auto-registro
Las herramientas no aparecen	Reiniciar tu agente de IA tras la instalación
Conexión rechazada	Verificar que el binario karajan-mcp está en tu PATH
Errores de SonarQube	Ejecutar kj_doctor para diagnosticar, o usar noSonar: true
Sesión atascada	Usar kj_report --list para encontrar la sesión, luego kj_resume