MCP Server

The most powerful way to use Karajan Code is as an MCP server inside your AI agent. Instead of switching between terminals and copy-pasting outputs, your agent sends tasks directly to kj_run and receives structured results — all within the conversation.

In practice — from your agent

One of those MCP tools is the project’s memory: kj_rag_query. Before your agent assumes what the codebase does, it can ask the index — and get an answer grounded in your actual code, docs and plans, not a guess. A sensitivity policy decides which model may see what, and secrets are excluded from the index, so the memory helps without leaking. You don’t run anything: the tool is there in the session, and a good agent reaches for it instead of grepping blind.

Under the hood — try it yourself

The same memory is a CLI, so you can query it directly:

kj rag index                       # build (or refresh) the index of this repo
kj rag query "where is the pre-loop stage defined?"   # a grounded answer, with sources

Re-index after a change (kj rag index --since <ref>) and the answers track the code. Nothing sensitive is embedded — the index is built with the sensitivity policy applied.

Auto-registration

After npm install -g karajan-code, the MCP server automatically registers in Claude Code and Codex. No manual setup required.

The postinstall hook writes the server configuration to:

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

Registration is idempotent — safe to run multiple times.

After updates: Transport closed

If you upgrade Karajan Code while your MCP host session is still open, the current karajan-mcp process may exit and the host can show Transport closed.

This is expected: since v1.57.0, Karajan MCP performs a graceful restart after npm updates. The server writes a restart marker and exits cleanly. The new instance detects the marker and starts with fresh code.

Quick recovery:

1. Restart your MCP host session (Claude/Codex).
2. Confirm the server is listed (codex mcp list or host equivalent).
3. Run kj_config (and optionally a short kj_plan) before long tasks.

Manual configuration

If auto-registration doesn’t work or you need custom paths:

Claude Code

Add to ~/.claude.json:

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

Codex

Add to ~/.codex/config.toml:

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

Custom MCP host

Start the server via stdio:

karajan-mcp

Or with an explicit path:

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

Available tools

Karajan Code exposes 27 MCP tools:

Tool	Required params	Description
kj_run	task	Run the full coder → sonar → reviewer pipeline
kj_discover	task	Pre-execution gap detection with 5 modes (gaps, momtest, wendel, classify, jtbd)
kj_code	task	Run coder-only mode (skip review)
kj_review	task	Run reviewer-only mode on the current diff
kj_plan	task	Generate an implementation plan with heartbeat/stall telemetry
kj_resume	sessionId	Resume a paused, stopped, or failed session
kj_preflight	humanResponse	Human confirms agent config before kj_run/kj_code executes
kj_agents	—	List or set AI agent per pipeline role (session/project/global scope)
kj_status	—	Dashboard with HU states, current stage, timing, progress. Returns structured JSON
kj_report	—	Read session reports with cost breakdown
kj_scan	—	Run SonarQube scan on the current project
kj_init	—	Initialize config, review rules, SonarQube, and BecarIA scaffolding (--scaffold-becaria)
kj_doctor	—	Check system dependencies and agent CLIs
kj_config	—	Show current configuration
kj_roles	—	List pipeline roles or show role templates
kj_triage	task	Classify task complexity and activate roles
kj_researcher	task	Investigate codebase context
kj_architect	task	Design solution architecture
kj_board	action	Start/stop/status HU Board dashboard
kj_hu	action	Manage user stories (create, update, list, get) in the local HU Board
kj_suggest	observation	Send an observation to Solomon without interrupting the pipeline
kj_skills	—	List, install, or remove domain-specific skills for pipeline roles
kj_undo	—	Revert last pipeline run (soft reset or hard)

See the MCP Tools Reference for complete parameter documentation.

Using kj_run

kj_run is the primary tool. It orchestrates the full pipeline and returns structured results.

Basic usage

From your AI agent, simply ask:

“Use kj_run to add input validation to the signup form”

The agent calls:

{
  "tool": "kj_run",
  "params": {
    "task": "Add input validation to the signup form"
  }
}

With options

{
  "tool": "kj_run",
  "params": {
    "task": "Fix the SQL injection vulnerability in search",
    "coder": "claude",
    "reviewer": "codex",
    "mode": "paranoid",
    "methodology": "tdd",
    "maxIterations": 5,
    "autoCommit": true
  }
}

With BecarIA Gateway

{
  "tool": "kj_run",
  "params": {
    "task": "Add input validation to the signup form",
    "enableBecaria": true
  }
}

When enableBecaria is true, Karajan creates an early draft PR after the first coder iteration and all agents (Coder, Reviewer, Sonar, Solomon, Tester, Security, Planner) post their results as PR comments/reviews. Configurable dispatch events trigger GitHub Actions workflows at each pipeline stage.

With Planning Game integration

{
  "tool": "kj_run",
  "params": {
    "task": "Implement user authentication",
    "pgTask": "PRJ-TSK-0042",
    "pgProject": "MyProject"
  }
}

The tool fetches the full card context (description, acceptance criteria) from Planning Game.

Real-time progress

During execution, Karajan sends real-time progress notifications via MCP logging. Your agent sees updates as each stage completes:

[1] coder:start — Writing code and tests...
[1] coder:end — Code generation complete
[1] sonar:start — Running SonarQube analysis...
[1] sonar:end — Quality gate passed
[1] reviewer:start — Reviewing code...
[1] reviewer:end — APPROVED
[1] session:end — Pipeline completed

Progress stages include: 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.

Cumulative pipeline tracker

In addition to individual stage events, Karajan emits a pipeline:tracker event after every stage transition with the full cumulative state:

{
  "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" }
    ]
  }
}

This lets MCP hosts render a single progress widget showing all stages at a glance, instead of interpreting individual events.

For single-agent tools (kj_code, kj_review, kj_plan), tracker start/end logs are also emitted via sendLoggingMessage.

Response format

Successful run

{
  "ok": true,
  "sessionId": "s_2026-02-28T20-47-24-270Z",
  "approved": true,
  "review": {
    "status": "approved",
    "summary": "Code meets all standards",
    "issues": [],
    "suggestions": ["Consider extracting validation to a helper"]
  },
  "git": {
    "committed": true,
    "commits": ["abc123"],
    "branch": "feat/signup-validation",
    "pushed": false
  }
}

Paused session

When fail-fast detection triggers or clarification is needed:

{
  "ok": false,
  "paused": true,
  "sessionId": "s_2026-02-28T20-47-24-270Z",
  "question": "The reviewer rejected the same issue twice. Should we proceed?",
  "context": "reviewer_fail_fast"
}

Resume with kj_resume:

{
  "tool": "kj_resume",
  "params": {
    "sessionId": "s_2026-02-28T20-47-24-270Z",
    "answer": "Yes, proceed with the current approach"
  }
}

Error response

{
  "ok": false,
  "error": "SonarQube is not reachable",
  "tool": "kj_run",
  "category": "sonar_unavailable",
  "suggestion": "Try: docker start sonarqube, or use noSonar: true"
}

Error categories: sonar_unavailable, auth_error, config_error, agent_missing, timeout, git_error.

Session management

Sessions persist to disk at $KJ_HOME/sessions/{sessionId}/. This enables:

• Pause/resume across agent conversations
• Cost tracking per session with kj_report
• Auto-cleanup of sessions older than session.expiry_days (default: 30)

Listing sessions

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

Cost breakdown

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

Returns a stage-by-stage breakdown with timing, tokens, and costs.

Companion MCPs

Karajan Code works well alongside other MCP servers:

MCP	How it complements Karajan
Planning Game	Task management — fetch tasks, update status, track sprints (MCP server)
GitHub	PR creation, issue management, CI/CD checks
Chrome DevTools	Visual verification of UI changes after coding
SonarQube	Direct access to quality reports (Karajan has built-in SonarQube, but the MCP adds direct query access)

Workflow example with Planning Game

1. Agent fetches the highest priority task from Planning Game MCP
2. Agent sends the task to kj_run
3. Karajan orchestrates coder → sonar → reviewer
4. Agent updates the card status to “To Validate” in Planning Game
5. Agent creates a PR via GitHub MCP

All within a single conversation, fully automated.

Troubleshooting

Problem	Solution
MCP server not found	Run npm install -g karajan-code to trigger auto-registration
Tools not appearing	Restart your AI agent after installation
Connection refused	Check that karajan-mcp binary is in your PATH
SonarQube errors	Run kj_doctor to diagnose, or use noSonar: true
Session stuck	Use kj_report --list to find the session, then kj_resume