CKB exposes AI-native code navigation and architectural memory capabilities via the Model Context Protocol (MCP), enabling AI assistants like Claude Code to discover, understand, and navigate codebases with persistent knowledge.

Looking for tool documentation? See MCP-Tools for complete reference documentation of all 76 MCP tools.

CKB works with any MCP-compatible AI coding tool.

# Install CKB
npm install -g @tastehub/ckb

# Configure for current project
ckb setup

# Or configure globally for all projects
ckb setup --global

# Verify configuration
claude mcp list

Or with npx (no install):

npx @tastehub/ckb setup

Manual configuration — add to .mcp.json in project root:

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

Or go to Settings → Cursor Settings → MCP → Add new global MCP server.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

Or go to Windsurf Settings → Advanced Settings → Cascade → Manage MCP Servers.

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "ckb": {
        "type": "stdio",
        "command": "npx",
        "args": ["@tastehub/ckb", "mcp"]
      }
    }
  }
}

Add to opencode.json in project root:

{
  "mcp": {
    "ckb": {
      "type": "local",
      "command": ["npx", "@tastehub/ckb", "mcp"],
      "enabled": true
    }
  }
}

Note: OpenCode uses a different config format - command is an array and requires type: "local".

Claude Desktop is a standalone app without a project context, so CKB needs to know which repository to analyze.

Automatic setup (recommended):

cd /path/to/your/repo
ckb setup --tool=claude-desktop

This prompts for your repository path and configures everything automatically.

Manual configuration — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["-y", "@tastehub/ckb", "mcp"],
      "env": {
        "CKB_REPO": "/path/to/your/repo"
      }
    }
  }
}

The CKB_REPO environment variable tells CKB which repository to analyze. You can also use the --repo flag directly:

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["-y", "@tastehub/ckb", "mcp", "--repo", "/path/to/your/repo"]
    }
  }
}

Important: Claude Desktop can only work with one repository at a time. To switch repositories, run ckb setup --tool=claude-desktop again or update the config manually.

On Windows, wrap the command with cmd /c in any of the configs above:

{
  "mcpServers": {
    "ckb": {
      "command": "cmd",
      "args": ["/c", "npx", "@tastehub/ckb", "mcp"]
    }
  }
}

If you built from source or installed globally, use the binary directly:

{
  "mcpServers": {
    "ckb": {
      "command": "ckb",
      "args": ["mcp"]
    }
  }
}

CKB exposes 76 tools, but most sessions only need a subset. Presets reduce token overhead by up to 83% by limiting exposed tools to task-relevant sets.

# List available presets
ckb mcp --list-presets

# Start with a preset
ckb mcp --preset=review

The AI can dynamically expand tools mid-session using expandToolset.

See Presets for complete documentation including tool lists for each preset, configuration examples, and token efficiency details.

For MCP clients that support pagination, CKB uses cursor-based pagination with:

• Page size: 15 tools per page
• Core-first ordering: Page 1 always contains the complete core toolset
• Cursor invalidation: Cursors rejected when preset or toolset changes

Non-paginating clients receive all tools in the current preset on the first request.

Tools are classified by performance budget. See MCP-Tools for the complete list organized by category.

searchSymbols · explainFile · listEntrypoints · explainPath · getSymbol · explainSymbol · getOwnership · getModuleResponsibilities · recordDecision · getDecisions · annotateModule · listFederations · federationStatus · federationRepos · daemonStatus · listSchedules · runSchedule · listWebhooks · testWebhook · webhookDeliveries · getFileComplexity · listContracts · suppressContractEdge · verifyContractEdge · getContractStats · getTelemetryStatus · getObservedUsage · explainOrigin · getDocsForSymbol · getSymbolsInDoc · getDocsForModule · federationAddRemote · federationRemoveRemote · federationListRemote · federationStatusRemote · federationListAllRepos

• Max 1 hop traversal
• Max 50 results
• No callgraph expansion or deep git history

traceUsage · getArchitecture · getHotspots · summarizeDiff · recentlyRelevant · listKeyConcepts · analyzeImpact · getCallGraph · findReferences · justifySymbol · federationSearchModules · federationSearchOwnership · federationGetHotspots · federationSearchDecisions · federationSync · analyzeContractImpact · getContractDependencies · findDeadCodeCandidates · analyzeCoupling · exportForLLM · auditRisk · indexDocs · checkDocStaleness · getDocCoverage · federationSyncRemote · federationSearchSymbolsHybrid

• Up to depth 5 traversal
• Up to 1000 git commits
• Must include limitations field

refreshArchitecture · summarizePr · getOwnershipDrift

• refreshArchitecture: Supports async mode (v6.1) — returns jobId for polling
• summarizePr: Analyze PR changes, suggest reviewers, assess risk
• getOwnershipDrift: Compare CODEOWNERS vs actual git-blame ownership

All 76 MCP tools now return responses wrapped in a standardized envelope with metadata:

{
  "schemaVersion": "1.0",
  "data": { /* tool-specific payload */ },
  "meta": {
    "confidence": {
      "score": 0.85,
      "tier": "medium",
      "reasons": ["SCIP+git hybrid"]
    },
    "provenance": {
      "backends": ["scip", "git"],
      "repoStateId": "abc123def456"
    },
    "freshness": {
      "indexAge": {
        "commitsBehind": 3,
        "staleReason": "behind-head"
      }
    },
    "truncation": {
      "isTruncated": true,
      "shown": 10,
      "total": 47,
      "reason": "max-results"
    }
  },
  "warnings": [
    { "code": "W001", "message": "Index slightly stale" }
  ],
  "error": null,
  "suggestedNextCalls": [
    {
      "tool": "getModuleOverview",
      "params": { "path": "internal/query" },
      "reason": "Explore top impacted module"
    }
  ]
}

Key Envelope Fields:

Score Modifiers:

getStatus() → listKeyConcepts() → getArchitecture() → listEntrypoints() → searchSymbols()

searchSymbols() → traceUsage() → getCallGraph() → recentlyRelevant()

searchSymbols() → explainSymbol() → findReferences() → analyzeImpact() → getHotspots()

summarizeDiff() → getHotspots() → getOwnership() → traceUsage()

searchSymbols() → justifySymbol() → explainFile()

getArchitecture() → getOwnership() → getModuleResponsibilities()

getDecisions() → recordDecision() → annotateModule()

findDeadCodeCandidates() → justifySymbol() → [check for "investigate" with ADR reasoning]

If justifySymbol returns "investigate" with reasoning mentioning an ADR, the code isn't dead—it was an intentional architectural decision. Only "remove-candidate" without ADR context suggests safe removal.

analyzeImpact() → [check relatedDecisions] → getDecisions()

When analyzeImpact shows relatedDecisions, read them before making changes to understand the architectural context.

getHotspots() → getOwnership() → summarizeDiff()

summarizePr() → getOwnershipDrift() → getHotspots()

refreshArchitecture({ async: true }) → getJobStatus() → [poll until complete]

listFederations() → federationStatus() → federationSearchModules() → federationGetHotspots()

federationSearchOwnership() → federationSearchDecisions() → federationSync()

daemonStatus() → listSchedules() → listWebhooks() → webhookDeliveries()

listSchedules() → runSchedule() → listJobs() → getJobStatus()

listContracts() → analyzeContractImpact() → getContractDependencies() → getContractStats()

listContracts() → analyzeContractImpact() → [contact owners] → federationSync()

getTelemetryStatus() → [verify coverage is medium+] → findDeadCodeCandidates() → justifySymbol()

searchSymbols() → getObservedUsage() → analyzeImpact({ includeTelemetry: true })

searchSymbols() → explainOrigin() → analyzeCoupling() → auditRisk()

analyzeCoupling() → getHotspots() → getOwnership()

exportForLLM() → [paste to LLM for codebase understanding]

auditRisk() → auditRisk({ quickWins: true }) → explainOrigin()

indexDocs() → checkDocStaleness({ all: true }) → getDocsForSymbol() → getDocCoverage()

searchSymbols() → getDocsForSymbol() → [rename symbol] → checkDocStaleness()

federationAddRemote() → federationSyncRemote() → federationStatusRemote() → federationSearchSymbolsHybrid()

federationListRemote() → federationSearchSymbolsHybrid({ servers: [...] }) → federationListAllRepos()

• ❌ Code mutation/refactoring
• ❌ Test generation
• ❌ Fix suggestions
• ❌ Policy enforcement
• ❌ Lint judgments

Navigation and comprehension only.

searchSymbols, getSymbol, findReferences, explainSymbol, justifySymbol, getCallGraph, getModuleOverview, analyzeImpact, getStatus, doctor

All v5.2 tools are now implemented:

Phase 1: explainFile, traceUsage, listEntrypoints

Phase 2: summarizeDiff

Phase 3: getHotspots, getArchitecture

Phase 4: explainPath, listKeyConcepts, recentlyRelevant

All v6.0 tools are implemented:

Phase 1: getArchitecture (enhanced), refreshArchitecture

Phase 2: getOwnership

Phase 3: getHotspots (enhanced with trends), getModuleResponsibilities

Phase 4: recordDecision, getDecisions, annotateModule

All v6.1 tools are implemented:

Background Jobs: getJobStatus, listJobs, cancelJob

Async Operations: refreshArchitecture now supports async: true mode

CI/CD Integration: summarizePr, getOwnershipDrift

All v6.2 tools are implemented:

Federation Management: listFederations, federationStatus, federationRepos, federationSync

Cross-Repo Queries: federationSearchModules, federationSearchOwnership, federationGetHotspots, federationSearchDecisions

All v6.2.1 tools are implemented:

Daemon Status: daemonStatus

Scheduler: listSchedules, runSchedule

Webhooks: listWebhooks, testWebhook, webhookDeliveries

Language-agnostic complexity metrics via getFileComplexity tool:

Supported Languages: Go, JavaScript, TypeScript (+ TSX), Python, Rust, Java, Kotlin

Metrics:

• Cyclomatic complexity — decision points analysis
• Cognitive complexity — nesting-weighted for maintainability

Integration: Complexity feeds into getHotspots risk scores

All v6.3 tools are implemented:

Contract Detection: listContracts

Impact Analysis: analyzeContractImpact, getContractDependencies

Edge Management: suppressContractEdge, verifyContractEdge

Statistics: getContractStats

All v6.4 tools are implemented:

Telemetry Status: getTelemetryStatus

Usage Display: getObservedUsage

Dead Code Detection: findDeadCodeCandidates

Enhanced Tools:

• analyzeImpact - Now includes includeTelemetry parameter for observed callers
• getHotspots - Now includes observedUsage field when telemetry is enabled

All v6.5 tools are implemented:

Symbol Explanation: explainOrigin

Co-Change Analysis: analyzeCoupling

LLM Export: exportForLLM

Risk Audit: auditRisk

Annotation Integration: ADRs and module annotations are now wired into core tools:

• explainSymbol - Now includes annotations field with related ADRs and module metadata
• justifySymbol - Verdict considers ADRs; returns "investigate" instead of "remove-candidate" when an accepted/proposed ADR exists for the module
• analyzeImpact - Now includes relatedDecisions field showing ADRs affecting impacted modules
• getModuleOverview - Now includes annotations and relatedDecisions fields
• getModuleResponsibilities - Declared annotations now override inferred responsibilities with higher confidence

All v7.3 tools are implemented:

Documentation Indexing: indexDocs

Symbol Queries: getDocsForSymbol, getSymbolsInDoc, getDocsForModule

Staleness Detection: checkDocStaleness

Coverage Analysis: getDocCoverage

Features:

• Backtick detection - Automatically detect Symbol.Name references in markdown
• Directive support - <!-- ckb:symbol --> for explicit references, <!-- ckb:module --> for module linking
• Fence scanning - Extract symbols from fenced code blocks (8 languages via tree-sitter)
• Staleness detection - Find broken references when symbols are renamed or deleted
• Rename awareness - Suggest new names when documented symbols are renamed via alias chain
• CI enforcement - --fail-under flag for documentation coverage thresholds
• known_symbols directive - Allow single-segment symbol detection

All v7.3 tools are implemented:

Server Management: federationAddRemote, federationRemoveRemote, federationListRemote

Synchronization: federationSyncRemote

Status & Health: federationStatusRemote

Hybrid Queries: federationSearchSymbolsHybrid, federationListAllRepos

Features:

• Remote server connections with Bearer token auth
• Environment variable expansion for tokens (${VAR} syntax)
• Configurable cache TTL and request timeout per server
• Hybrid local+remote queries with source attribution
• Graceful degradation when remotes unavailable
• Exponential backoff retry logic (max 3 retries)
• SQLite caching layer for remote metadata

All v7.3 multi-repo tools are implemented:

Registry Management: listRepos, getActiveRepo

Context Switching: switchRepo

Features:

• Global repository registry at ~/.ckb/repos.json
• Named shortcuts for quick context switching in MCP sessions
• Multi-engine support (up to 5 engines in memory with LRU eviction)
• Per-repo configuration loading from each repo's .ckb/config.json
• Repo state tracking: valid, uninitialized, missing
• --repo flag for ckb mcp and ckb serve to start with specific repo
• Graceful engine lifecycle with in-flight operation tracking

CLI Commands:

• ckb repo add [name] [path] - Register a repository
• ckb repo list - List repos grouped by state
• ckb repo remove <name> - Unregister a repo
• ckb repo default [name] - Get or set default repo
• ckb repo which - Print current repo (for scripts)
• ckb repo check - Validate all registered repos

All 74 MCP tool responses now include structured metadata:

Envelope Features:

• Schema version for forward compatibility
• Confidence scoring with tiers (high/medium/low/speculative)
• Provenance tracking (which backends contributed)
• Freshness metadata (index staleness)
• Truncation awareness (shown vs total counts)
• Structured suggested next calls

Files Added:

• internal/envelope/envelope.go — Core types and builder
• internal/mcp/tool_helpers.go — MCP-specific response helpers

Total: 76 MCP tools available

Good news: As of CKB 7.3, this is handled automatically. The Node.js shim now detects your repo root and sets CKB_REPO for you.

Background: When npx runs CKB, it executes from a sandboxed temp directory (like ~/.npm/_npx/...), not your project directory. CKB needs to find .ckb/ in the project root.

How CKB 7.3+ fixes this: The npm package includes a shim that walks up from process.cwd() looking for .ckb/ or .git/ and automatically sets CKB_REPO. This means simple configs now work:

{
  "command": "npx",
  "args": ["@tastehub/ckb", "mcp"]
}

If auto-detection fails (rare edge cases), you can still set CKB_REPO explicitly:

{
  "command": "npx",
  "args": ["-y", "@tastehub/ckb", "mcp"],
  "env": {
    "CKB_REPO": "/path/to/your/repo"
  }
}

Limitation: With auto-detected or explicit CKB_REPO, CKB works with one repository at a time. To switch repos, update the config or use project-scoped configuration.

If you use NVM, asdf, or other Node version managers, npx may not work correctly because these tools rely on shell initialization that MCP clients don't run.

Symptoms:

• "command not found: npx"
• Server starts but uses wrong Node version
• Intermittent failures

Solution: Use absolute paths instead of npx:

{
  "mcpServers": {
    "ckb": {
      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/node",
      "args": [
        "/Users/you/.nvm/versions/node/v22.11.0/lib/node_modules/@tastehub/ckb/bin/ckb.js",
        "mcp"
      ]
    }
  }
}

Find your paths:

# Find node path
which node

# Find global package location
npm root -g

Alternative: Install CKB globally with the system Node (not NVM):

/usr/local/bin/npm install -g @tastehub/ckb

MCP clients typically only pass PATH to servers. Other environment variables like $HOME are NOT automatically available.

What works:

• PATH (usually)
• Variables explicitly listed in env config

What doesn't work:

• $HOME, $USER, custom variables
• Variable substitution (${VAR}) in config files
• Shell expansion

If CKB needs specific variables, add them explicitly:

{
  "env": {
    "HOME": "/Users/you",
    "CKB_REPO": "/path/to/repo"
  }
}

Process orphaning: Cursor doesn't always terminate MCP servers when closing. You may need to manually kill orphaned processes:

pkill -f "ckb mcp"

Sandbox environment: When using npx, Cursor runs servers in a sandboxed temp directory. Use CKB_REPO or project-scoped config.

Logging disabled: Cursor breaks MCP logging connections. Debug by writing to a file instead:

ckb mcp 2>/tmp/ckb-debug.log

Config location varies:

• Official: ~/.codeium/windsurf/mcp_config.json
• Legacy: ~/.codeium/mcp_config.json

CKB's setup command probes both locations and uses whichever exists.

Global-only: Windsurf only supports global MCP configuration, not per-project. Consider using CKB_REPO if you work with multiple repositories.

# Check if ckb is available
npx @tastehub/ckb version

# Test MCP server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | npx @tastehub/ckb mcp

# If using NVM, check with absolute path
/path/to/node /path/to/ckb mcp --help

Common causes:

1. Wrong working directory — CKB can't find .ckb/ database

   # Fix: Add CKB_REPO to config
   "env": { "CKB_REPO": "/path/to/your/repo" }

2. npx not found (NVM/asdf users)

   # Fix: Use absolute paths instead of npx

3. Non-JSON output to stdout — Check for rogue print statements

   # Test: Should output only JSON
   echo '{}' | ckb mcp 2>/dev/null

# Check CKB is initialized
ls -la .ckb/

# Initialize if missing
ckb init

# Check status
ckb status

# Regenerate SCIP index
ckb index

# Check for issues
ckb doctor

# Force refresh architecture
ckb refresh --force

# macOS: Watch MCP logs (Claude Desktop)
tail -f ~/Library/Logs/Claude/mcp*.log

# Write debug output to file
CKB_REPO=/path/to/repo ckb mcp 2>/tmp/ckb-mcp.log

• MCP-Tools — Complete tool reference documentation
• Presets — Tool presets for token optimization
• Prompt-Cookbook — Example prompts and workflows
• API-Reference — HTTP API documentation
• Quick-Start — Initial setup guide
• Configuration — MCP server configuration options