MCP Server

Karajan Code also runs as an MCP server inside your AI agent. Your agent does the work; through the server it reaches the project’s memory (kj_rag_query), the board (kj_hu) and the coder declared in your panel (kj_code) without leaving 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
kj rag query "how is billing computed?" --where source~=src/billing   # stay inside a folder or module

--where takes key=value pairs joined by AND (symbol=loadConfig, hu_id=HU-003 AND kind=plan) and, since 4.63, key~=prefix: source~=src/billing keeps the answer inside that folder, relative to the project. Hybrid retrieval fuses the semantic and the keyword lists by reciprocal rank (rag.search.rrf_k, 60 by default); the old alpha weight no longer applies. A cross-encoder can re-score the top 40 before the top-K is cut (--rerank, or rag.search.rerank.enabled: true in kj.config.yml; needs @huggingface/transformers): off by default, since on the frozen corpus it kept the same MRR and doubled the p95 latency.

Long documents are read by index, not whole: kj doc index <file> lists the headings of a markdown file and kj doc section <file> "<heading>" prints one section exactly as the file has it. Over docs.indexFirstBytes (12 000 characters by default), a task file or an ADR reaches the roles as its headings plus that command, so the prompt carries only what the task needs.

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 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 17 MCP tools:

Tool	Required params	Description
kj_rag_query	text	Semantic search over the project’s code, plans and onboarding brief
kj_rag_index	—	(Re)index this project into the local vector store
kj_hu	action	Manage user stories (create, update, list, get) in the HU Board
kj_board	action	Start/stop/status HU Board dashboard
kj_code	task	Have the coder declared in your panel write the change
kj_preflight	humanResponse	Human confirms the agent config before the first kj_code
kj_discover	task	Gap detection before the work starts (gaps, momtest, wendel, classify, jtbd)
kj_audit	—	Codebase health analysis, read-only
kj_scan	—	Run SonarQube scan on the current project
kj_suggest	observation	Propose an observation to Solomon
kj_agents	—	List or set the AI agent assigned to each role
kj_roles	—	List roles or show role templates
kj_report	—	Read session reports
kj_init	—	Initialize config, review rules and SonarQube
kj_doctor	—	Check system dependencies and agent CLIs
kj_config	—	Show current configuration
kj_clean	—	Garbage-collect stale Karajan state (dry-run by default)

Retired in 5.0

kj_run, kj_resume, kj_plan, kj_status, kj_undo, kj_review, kj_triage, kj_researcher and kj_architect drove the old pipeline and were retired with it. A call answers with a notice and starts nothing. What replaces each one: Migrating to 5.0.

Skills, commands and subagents are served by atril, not by the kj server (since 5.0, kj_skills is gone). To search, resolve, install or remove them over MCP, add atril mcp as a second server.

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 and puts it on the board (kj_hu)
2. Agent asks the project’s memory (kj_rag_query) before touching the code
3. Agent writes the change test-first (or hands it to the panel coder with kj_code) and gets kj review --staged before each commit
4. Agent creates a PR via GitHub MCP
5. Agent updates the card status to “To Validate” in Planning Game

All within a single conversation, under the same gates.

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