Auto-activated — this skill loads automatically when Claude detects matching context.

OrchestKit Configuration

Interactive setup for customizing your OrchestKit installation.

Quick Start

/ork:configure
/ork:configure mcp memory

Argument Resolution

PRESET = "$ARGUMENTS[0]"   # Optional preset name or subcommand, e.g., "mcp"
TARGET = "$ARGUMENTS[1]"   # Optional target, e.g., "memory"
# If no arguments, run interactive wizard.
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

Step 1: Choose Preset

Use AskUserQuestion:

Step 2: Customize Skill Categories

Categories available:

• AI/ML (28 skills)
• Backend (16 skills)
• Frontend (9 skills)
• Testing (14 skills)
• Security (7 skills)
• DevOps (5 skills)
• Planning (7 skills)
• Workflow (5 skills)

Step 3: Customize Agents

Product Agents (2):

• market-intelligence
• product-strategist

Technical Agents (17):

• backend-system-architect
• frontend-ui-developer
• database-engineer
• llm-integrator
• workflow-architect
• data-pipeline-engineer
• test-generator
• code-quality-reviewer
• security-auditor
• security-layer-auditor
• debug-investigator
• system-design-reviewer
• python-performance-engineer
• frontend-performance-engineer
• monitoring-engineer
• event-driven-architect
• infrastructure-architect

Operations Agents (6):

• ci-cd-engineer
• deployment-manager
• git-operations-engineer
• release-engineer
• ai-safety-auditor
• multimodal-specialist

Research Agents (4):

• web-research-analyst
• market-intelligence
• design-system-architect
• demo-producer

Step 4: Configure Hooks

Safety Hooks (Always On):

• git-branch-protection
• file-guard
• redact-secrets

Toggleable Hooks:

• Productivity (auto-approve, logging)
• Quality Gates (coverage, patterns)
• Team Coordination (locks, conflicts)
• Notifications (desktop, sound)

CC 2.1.49 Managed Settings: OrchestKit ships plugin settings.json with default hook permissions. These are managed defaults — users can override them in project or user settings. Enterprise admins can lock managed settings via managed profiles.

Step 5: Configure MCPs (Optional)

All 5 MCPs ship enabled by default. Tavily requires an API key; agentation requires a local package install.

Why all enabled? OrchestKit ships 30+ Sonnet/Haiku subagents. While Opus 4.6 has native extended thinking, Sonnet and Haiku do not — they benefit from sequential-thinking. Tavily and agentation are used by specific agents (see mcpServers in agent frontmatter). CC's MCPSearch auto-defers schemas when overhead exceeds 10% of context, so token cost is managed automatically.

Background agents: MCP tools are NOT available in background subagents (hard CC platform limitation). Agents that need MCP tools must run in the foreground.

Already have these MCPs installed globally? If Tavily or memory are already in your ~/.claude/mcp.json, skip enabling them here to avoid duplicate entries. OrchestKit agents will use whichever instance Claude Code resolves first.

Opt out of claude.ai MCP servers (CC 2.1.63+): Claude Code may load MCP servers from claude.ai by default. To disable this and only use locally-configured MCPs:

export ENABLE_CLAUDEAI_MCP_SERVERS=false

Add to your shell profile (~/.zshrc or ~/.bashrc) to persist across sessions. This only affects MCP servers sourced from claude.ai — locally-configured MCPs in .mcp.json and ~/.claude/mcp.json are unaffected.

Steps 6-9: CC Version-Specific Settings

Load details: Read("$\{CLAUDE_SKILL_DIR\}/references/cc-version-settings.md") for full configuration options.

Covers CC 2.1.7 (MCP deferral threshold, effective context window), CC 2.1.20 (task deletion, PR enrichment, agent permissions, monorepo detection, team distribution), CC 2.1.23 (spinner verbs customization), and CC 2.1.79 (turn duration display).

Step 10: Webhook & Telemetry Configuration

Configure dual-channel telemetry for streaming session data to HQ or your own API.

AskUserQuestion(questions=[{
  "question": "Set up session telemetry?",
  "header": "Telemetry",
  "options": [
    {"label": "Full streaming (Recommended)", "description": "All 18 events stream via native HTTP + enriched summaries"},
    {"label": "Summary only", "description": "SessionEnd and worktree events only (command hooks)"},
    {"label": "Skip", "description": "No telemetry — hooks run locally only"}
  ],
  "multiSelect": false
}])

If "Full streaming"

1. Ask for webhook URL:

AskUserQuestion(questions=[{
  "question": "What is your webhook endpoint URL?",
  "header": "Webhook URL",
  "options": [
    {"label": "Custom URL", "description": "Enter your API endpoint (e.g., https://api.example.com/hooks)"}
  ],
  "multiSelect": false
}])

2. Run the HTTP hook generator:

npm run generate:http-hooks -- <webhook-url> --write

3. Save webhookUrl to orchestration config for command hooks:

# File: .claude/orchestration/config.json
saveConfig({ webhookUrl: "<webhook-url>" })

4. Remind the user to set the auth token:

Set ORCHESTKIT_HOOK_TOKEN in your environment (never in config files):
  export ORCHESTKIT_HOOK_TOKEN=your-secret

Two channels now active:
  Channel 1 (HTTP):    All 18 events → /cc-event (Bearer auth, zero overhead)
  Channel 2 (Command): SessionEnd → /ingest (HMAC auth, enriched data)

If "Summary only"

Save webhookUrl to config and remind about env var (same as above, skip generator step).

Load Read("$\{CLAUDE_SKILL_DIR\}/references/http-hooks.md") for architecture details.

Step 11: Optional Integrations

Load details: Read("$\{CLAUDE_SKILL_DIR\}/references/integrations.md") for full integration setup steps.

Covers Agentation UI annotation tool (npm install, MCP config, component scaffold, CSP updates). All steps are idempotent.

Step 12: Preview & Save

Tip (CC 2.1.69+): After saving configuration changes, run /reload-plugins to activate them without restarting your session.

Save to: ~/.claude/plugins/orchestkit/config.json

{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true, "backend": true, ... },
  "agents": { "product": true, "technical": true },
  "hooks": { "safety": true, "productivity": true, ... },
  "mcps": { "context7": false, ... }
}

VSCode: Remote Control (CC 2.1.79+)

VSCode users can run /remote-control to bridge their terminal session to claude.ai/code. This lets you continue the same session from a browser or phone — useful for monitoring long-running configurations or agent tasks away from your desk.

Related Skills

• ork:doctor: Diagnose configuration issues

References

Load on demand with Read("$\{CLAUDE_SKILL_DIR\}/references/<file>"):

Rules (2)

Backup existing configuration before making changes to enable safe rollback — HIGH

Backup Config Before Modification

Why

Configuration files accumulate user customizations over time (MCP servers, hook permissions, keybindings). Overwriting without backup means one bad write can destroy hours of setup with no recovery path.

Rule

Before modifying any configuration file:

1. Check if the file exists
2. If it exists, create a timestamped backup
3. Apply changes to the original
4. Report the backup location to the user

Incorrect — overwrite config without backup

# Directly overwrite existing config
cat > ~/.claude/plugins/orchestkit/config.json << 'EOF'
{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true }
}
EOF

// Blind write — existing customizations lost
import { writeFileSync } from "fs";

writeFileSync(configPath, JSON.stringify(newConfig, null, 2));

Problems:

• User's existing MCP server config is destroyed
• Custom hook permissions are lost
• No way to revert if new config causes failures

Correct — backup then modify

# Backup existing config with timestamp
CONFIG="$HOME/.claude/plugins/orchestkit/config.json"
if [ -f "$CONFIG" ]; then
  BACKUP="${CONFIG}.backup.$(date +%Y%m%d_%H%M%S)"
  cp "$CONFIG" "$BACKUP"
  echo "Backup saved: $BACKUP"
fi

# Now safe to write new config
cat > "$CONFIG" << 'EOF'
{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true }
}
EOF

import { existsSync, copyFileSync, writeFileSync } from "fs";

function safeWriteConfig(configPath: string, newConfig: object): string | null {
  let backupPath: string | null = null;

  if (existsSync(configPath)) {
    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
    backupPath = `${configPath}.backup.${timestamp}`;
    copyFileSync(configPath, backupPath);
  }

  writeFileSync(configPath, JSON.stringify(newConfig, null, 2));
  return backupPath;
}

Rollback Pattern

# If something goes wrong, restore from backup
CONFIG="$HOME/.claude/plugins/orchestkit/config.json"
LATEST_BACKUP=$(ls -t "${CONFIG}.backup."* 2>/dev/null | head -1)
if [ -n "$LATEST_BACKUP" ]; then
  cp "$LATEST_BACKUP" "$CONFIG"
  echo "Restored from: $LATEST_BACKUP"
fi

Validate configuration after writing to catch malformed JSON and invalid settings — HIGH

Validate Config After Writing

Why

Configuration files are consumed by Claude Code's plugin loader. A malformed JSON file, a missing required field, or an invalid enum value will silently fail to load — the user sees no error, just missing functionality.

Rule

After every config write:

1. Parse the written file as JSON to verify syntax
2. Validate required fields exist
3. Validate field values against allowed enums
4. Report success or failure to the user

Incorrect — write config and assume success

# Write config, no verification
cat > config.json << 'EOF'
{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true }
}
EOF
echo "Configuration saved successfully!"

writeFileSync(configPath, JSON.stringify(config, null, 2));
console.log("Done!"); // No verification that file is valid

Problems:

• Truncated writes (disk full) produce invalid JSON
• Missing trailing brace from template errors breaks parsing
• Typo in preset name ("compelte") silently falls back to defaults

Correct — write then validate

CONFIG="$HOME/.claude/plugins/orchestkit/config.json"

cat > "$CONFIG" << 'EOF'
{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true }
}
EOF

# Validate JSON syntax
if ! python3 -c "import json; json.load(open('$CONFIG'))"; then
  echo "ERROR: Written config is not valid JSON"
  exit 1
fi

# Validate required fields
python3 -c "
import json, sys
config = json.load(open('$CONFIG'))
required = ['version', 'preset']
missing = [f for f in required if f not in config]
if missing:
    print(f'ERROR: Missing required fields: {missing}')
    sys.exit(1)
valid_presets = ['complete', 'standard', 'lite', 'hooks-only', 'monorepo']
if config.get('preset') not in valid_presets:
    print(f'ERROR: Invalid preset \"{config[\"preset\"]}\". Must be one of: {valid_presets}')
    sys.exit(1)
print('Config validated successfully')
"

import { readFileSync, writeFileSync } from "fs";

function writeAndValidateConfig(path: string, config: PluginConfig): void {
  const content = JSON.stringify(config, null, 2);
  writeFileSync(path, content);

  // Read back and validate
  const written = readFileSync(path, "utf-8");
  const parsed = JSON.parse(written); // Throws on malformed JSON

  const VALID_PRESETS = ["complete", "standard", "lite", "hooks-only", "monorepo"];
  if (!parsed.version) throw new Error("Missing required field: version");
  if (!VALID_PRESETS.includes(parsed.preset)) {
    throw new Error(`Invalid preset "${parsed.preset}"`);
  }
}

Validation Checklist

References (5)

Cc Version Settings

CC Version-Specific Settings

Step 6: CC 2.1.7 Settings

Configure CC 2.1.7-specific features:

MCP Auto-Deferral Threshold

MCP deferral threshold (default 10%): 10

Adds to config.json:

{
  "cc217": {
    "mcp_defer_threshold": 0.10,
    "use_effective_window": true
  }
}

Effective Context Window Mode

Use effective context window for calculations? [Y/n]: y

When enabled:

• Statusline shows context_window.effective_percentage
• Compression triggers use effective window
• MCP deferral more accurate

Step 7: CC 2.1.20 Settings

Configure CC 2.1.20-specific features:

Task Deletion Support

Enable task deletion (status: "deleted")? [Y/n]: y

Enables orphan detection and automatic cleanup of blocked tasks.

PR Status Enrichment

Enable PR status enrichment at session start? [Y/n]: y

Detects open PRs on current branch and sets ORCHESTKIT_PR_URL / ORCHESTKIT_PR_STATE env vars.

Background Agent Permission Pre-Mapping

Enable permission profile suggestions for agents? [Y/n]: y

Shows recommended permission profiles when spawning agents.

Monorepo Multi-Directory Detection

Enable monorepo detection? [Y/n]: y

Detects monorepo indicators and suggests --add-dir usage.

CC 2.1.47: When added_dirs are already active, the monorepo detector automatically skips the --add-dir suggestion. The added_dirs field is now available in hook inputs for multi-directory awareness.

Team Plugin Distribution (CC 2.1.45+)

Share OrchestKit across a team using a shared directory:

# Create shared plugin directory
mkdir -p /shared/team/plugins/orchestkit

# Copy plugin files
cp -r plugins/ork/* /shared/team/plugins/orchestkit/

# Team members use --add-dir to pick up the shared plugin
claude --add-dir /shared/team/plugins

CC 2.1.45+ supports plugin_hot_reload — team members get updates without restarting their sessions.

enabledPlugins vs added_dirs: enabledPlugins is a CC-internal concept and is NOT exposed to hooks. The hook-accessible field for multi-directory awareness is added_dirs (available in HookInput since CC 2.1.47). Hooks can read input.added_dirs to detect which additional directories are active — useful for adapting behavior in multi-repo workspaces.

Monorepo Package Context (CC 2.1.49)

When added_dirs are active, OrchestKit's monorepo detector surfaces package names from each directory as session context. This helps agents understand which packages are in scope:

Multi-directory context active (3 dirs)
Packages: @myapp/api, @myapp/web, @myapp/shared
Each directory may have its own CLAUDE.md with targeted instructions.

Use claude --add-dir ./packages/api --add-dir ./packages/web to include specific packages.

Step 8: CC 2.1.23 Settings

Configure CC 2.1.23-specific features:

Spinner Verbs Customization

Replace default Claude Code spinner verbs ("Thinking", "Working", etc.) with custom branding:

Customize spinner verbs? [Y/n]: y

Adds to .claude/settings.json:

{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": [
      "Orchestrating",
      "Coordinating",
      "Synthesizing",
      "Analyzing",
      "Reasoning",
      "Crafting",
      "Architecting",
      "Validating",
      "Dispatching",
      "Assembling",
      "Engineering",
      "Composing"
    ]
  }
}

Options:

• mode: "replace" - Use only your custom verbs
• mode: "append" - Add your verbs to the defaults

OrchestKit-themed verbs focus on orchestration, architecture, and engineering actions.

Step 9: CC 2.1.79 Settings

Configure CC 2.1.79-specific features:

Turn Duration Display

The /config menu now includes a "Show turn duration" toggle.

Enable turn duration in statusline? [y/N]: y

Adds to settings.json:

{
  "statusline": {
    "showTurnDuration": true
  }
}

Step 10: CC 2.1.80 Settings

Configure CC 2.1.80-specific features:

Effort Frontmatter

Skills can now declare effort: in frontmatter to override the model effort level when invoked. OrchestKit sets effort on 40 skills (18 high, 22 low).

Rate Limits Statusline

The statusline now receives rate_limits with 5-hour and 7-day usage windows. OrchestKit surfaces this in the status bar.

Source: Settings Marketplace

Plugin entries can be declared inline in settings.json:

{
  "plugins": {
    "sources": [
      { "type": "settings", "url": "github:yonatangross/orchestkit" }
    ]
  }
}

Channels (Research Preview)

MCP servers can push messages into sessions via --channels. Experimental — monitor for GA.

Shows elapsed time per turn in the statusline — useful for profiling slow tool calls and understanding agent performance.

Step 11: CC 2.1.81 Settings

Bare Mode for Scripted Calls

The --bare flag skips hooks, LSP, plugin sync, and skill directory walks for scripted -p calls. Ideal for eval pipelines and CI grading where plugin context is unnecessary.

Requirements:

• ANTHROPIC_API_KEY must be set (OAuth and keychain auth disabled in bare mode)
• Use with --settings to provide an apiKeyHelper if not using env var

# Fast grading call — no plugin overhead
claude -p "Grade this output..." --bare --max-turns 1 --output-format text

# With custom settings
claude -p "Classify..." --bare --settings ./eval-settings.json --json-schema schema.json

Channels Permission Relay

Channel servers that declare the permission capability can forward tool approval prompts to your phone. Useful for long-running multi-agent workflows (brainstorm, implement, verify) where you're away from terminal.

# Start session with channels enabled
claude --channels

# Channel server receives permission prompts and relays approval/denial

Configure channel servers in settings.json:

{
  "channels": {
    "servers": [
      { "url": "https://your-channel-server.example.com" }
    ]
  }
}

Plan Mode Context Clearing

Plan mode now hides the "clear context" option by default when accepting a plan. Restore with:

{
  "showClearContextOnPlanAccept": true
}

Plugin Freshness

Ref-tracked plugins now re-clone on every load to pick up upstream changes. For stability, pin to a specific version tag:

{
  "plugins": {
    "sources": [
      { "type": "settings", "url": "github:yonatangross/orchestkit@v7.20.0" }
    ]
  }
}

Use @main for bleeding edge, @v7.x.x for stability.

CC 2.1.90 Settings

Offline Plugin Resilience

Keep marketplace cache when git pull fails (useful for offline or restricted network environments):

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Format-on-Save Hooks (now viable)

CC 2.1.90 fixed the "File content has changed" race condition when a PostToolUse hook reformats files between consecutive edits. This enables format-on-save patterns:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "command": "prettier --write \"$CLAUDE_FILE_PATH\"",
      "timeout": 5
    }]
  }
}

/powerup Lessons

CC 2.1.90 adds /powerup — interactive lessons teaching features with animated demos. Reference this in onboarding or setup flows for new users.

CC 2.1.91 Settings

MCP Tool Result Persistence Override

MCP servers can now declare large results (up to 500K chars) that should not be truncated, using the _meta annotation:

{
  "_meta": {
    "anthropic/maxResultSizeChars": 500000
  },
  "content": [{ "type": "text", "text": "..." }]
}

Use this for results like database schemas, API specs, or code analysis that lose meaning when truncated. OrchestKit's mcp-output-transform hook respects this annotation and skips truncation when present.

Disable Skill Shell Execution

New disableSkillShellExecution setting prevents inline shell commands in skills, custom slash commands, and plugin commands from executing:

{
  "disableSkillShellExecution": true
}

Useful for enterprise environments where skills should only provide guidance, not execute commands. OrchestKit skills with invocation_hooks (cover, expect, commit, devops-deployment) will have their shell preconditions skipped when this is enabled.

Plugin Executables (bin/)

Plugins can now ship executables under a bin/ directory. These are invokable as bare commands from the Bash tool without full path qualification. OrchestKit uses this for run-hook.mjs and file-suggestion.sh.

Edit Tool Shorter Anchors

CC 2.1.91 uses shorter old_string anchors in the Edit tool, reducing output tokens. No configuration needed — this is an automatic optimization that benefits all users.

permissions.defaultMode: "auto" Validation

permissions.defaultMode: "auto" is now validated by JSON schema in settings.json. Previously this value was silently accepted but could cause issues. OrchestKit's settings already use valid permission modes.

CC 2.1.92 Settings

forceRemoteSettingsRefresh Policy

New managed policy setting for enterprise deployments. When set, CC blocks startup until remote managed settings are freshly fetched and exits if the fetch fails (fail-closed):

{
  "policy": {
    "forceRemoteSettingsRefresh": true
  }
}

Use case: Enterprise environments where stale managed settings (permission policies, plugin allowlists, sandbox rules) are a compliance risk. Without this, CC falls back to cached remote-settings.json from a prior session.

Trade-off: Startup requires network access — offline/air-gapped environments will fail to launch. Combine with managed-settings.d/ (CC 2.1.83) for local policy fragments as fallback.

Doctor check: ork:doctor warns if forceRemoteSettingsRefresh is set without a configured remote settings endpoint.

Remote Control Session Naming

Remote Control session names now default to your hostname as prefix (e.g. myhost-graceful-unicorn). Override with:

claude --remote-control-session-name-prefix "my-prefix"

Removed Commands

• /tag — removed. No replacement needed.
• /vim — removed. Toggle vim mode via /config → Editor mode instead.

Http Hooks

HTTP Hooks — Dual-Channel Telemetry (CC 2.1.63+)

OrchestKit supports two parallel channels for streaming session data:

• Channel 1: Native HTTP hooks — CC POSTs raw JSON to HQ for ALL 18 event types (zero overhead)
• Channel 2: Command hooks — Node spawn for enriched reporting (token usage, metrics, HMAC auth)

Quick Start

# 1. Generate native HTTP hook config for all 18 events
npm run generate:http-hooks -- https://your-api.com/hooks --write

# 2. Set auth token
export ORCHESTKIT_HOOK_TOKEN=your-secret-token

This writes to .claude/settings.local.json (not committed). CC merges plugin hooks.json + user settings.local.json — both channels fire in parallel.

Known Limitation (CC 2.1.71+): HTTP hooks must use real URLs, not env var placeholders. CC validates url fields as proper URLs before expanding $\{ENV_VAR\} — so "url": "$\{ORCHESTKIT_HOOK_URL\}" fails validation and breaks ALL hooks. This is why HTTP hooks are generated per-user with real URLs (not shipped in the plugin). Env var expansion in headers (e.g., $ORCHESTKIT_HOOK_TOKEN) works fine — only the url field is affected.

User Tiers

Channel Comparison

Generator CLI

# Print to stdout
npm run generate:http-hooks -- https://your-api.com/hooks

# Write to default location (.claude/settings.local.json)
npm run generate:http-hooks -- https://your-api.com/hooks --write

# Dry run (preview without writing)
npm run generate:http-hooks -- https://your-api.com/hooks --dry-run

# Custom path
npm run generate:http-hooks -- https://your-api.com/hooks --write --path ~/.claude/settings.local.json

The generator is idempotent — running twice replaces existing cc-event entries without duplicating.

Generated Config Format

Each event type gets a native HTTP hook entry:

{
  "hooks": {
    "SessionStart": [{
      "type": "http",
      "url": "https://your-api.com/hooks/cc-event",
      "headers": { "Authorization": "Bearer $ORCHESTKIT_HOOK_TOKEN" },
      "allowedEnvVars": ["ORCHESTKIT_HOOK_TOKEN"],
      "timeout": 5
    }],
    "UserPromptSubmit": [{ "...same..." }],
    "PreToolUse": [{ "...same..." }],
    "...": "...all 18 events..."
  }
}

What HQ Gets Per Event (natively from CC)

Security

• Bearer token auth via ORCHESTKIT_HOOK_TOKEN
• allowedEnvVars whitelist prevents env var leakage
• HTTP errors are non-blocking (graceful degradation)
• Security hooks (blocker, scanner, guard) stay type: "command" — never HTTP
• Token never stored in config files — env var only

Disabling

Remove the generated entries from .claude/settings.local.json, or delete the file entirely. Plugin command hooks continue working independently.

Integrations

Optional Integrations

Agentation (UI Annotation Tool)

Enable Agentation UI annotation tool? [y/N]: y

Agentation lets you annotate your app's UI in the browser and have Claude pick up the feedback automatically.

When enabled, perform these steps (idempotent — skip any step already done):

1. Install dependencies (check package.json first):

   npm install -D agentation agentation-mcp

2. Add MCP server to .mcp.json (skip if agentation key already exists):

   {
     "mcpServers": {
       "agentation": {
         "command": "npx",
         "args": ["-y", "agentation-mcp", "server"],
         "disabled": false
       }
     }
   }

3. Enable MCP server in Claude Code settings — add "agentation" to the enabledMcpjsonServers array in .claude/settings.local.json (create file if missing, skip if already listed):

   {
     "enabledMcpjsonServers": ["agentation"]
   }

4. Scaffold wrapper component — create a dev-only client component (skip if file already exists). Use the project's component directory (e.g. src/components/, components/, or app/components/):

   // agentation-wrapper.tsx
   "use client";
   
   import { Agentation } from "agentation";
   
   export function AgentationWrapper() {
     if (process.env.NODE_ENV !== "development") return null;
     return <Agentation endpoint="http://localhost:4747" webhookUrl="http://localhost:4747" />;
   }

   Then instruct the user to add <AgentationWrapper /> to their root layout.

5. CSP update (only if the project has a Content-Security-Policy): add http://localhost:4747 to the connect-src directive for development mode only.

Mcp Config

MCP Configuration

MCPs (Model Context Protocol servers) enhance OrchestKit commands but are NOT required. Commands work without them - MCPs just add extra capabilities.

Available MCPs

Subagent Model Note: Sequential-thinking MCP is redundant for Opus 4.6+ (which has native adaptive thinking), but OrchestKit ships 30+ Sonnet/Haiku subagents that do not have native extended thinking. These subagents benefit from sequential-thinking for complex multi-step reasoning. Enable it for the subagent mix, not the parent model.

Recommended MCPs by Project Type

Not sure which MCPs to enable? Match your project type:

All MCPs are optional — OrchestKit works without any. Enable what fits your workflow. See setup instructions for each MCP in the Dependencies section below.

Default State

OrchestKit ships all 5 MCPs enabled in .mcp.json. Tavily requires an API key (TAVILY_API_KEY via 1Password) — it connects but tools fail without the key. Agentation requires npm install -D agentation-mcp.

Two-Layer MCP Control (CC 2.1.49)

CC uses two layers to determine which MCP servers are active. Understanding both prevents configuration contradictions.

Layer 1: .mcp.json — Server definitions and self-declaration

• "disabled": false (or omitted) → server process starts, tools load
• "disabled": true → server process does NOT start, 0 tokens consumed

Layer 2: settings.json / settings.local.json — User approval

• enableAllProjectMcpServers: true → overrides Layer 1's disabled flag for all servers
• enabledMcpjsonServers: [...] → allowlist of approved servers
• disabledMcpjsonServers: [...] → denylist (takes precedence over allowlist)

Important: enableAllProjectMcpServers: true overrides disabled: true in .mcp.json. If you want a server truly off, either remove it from .mcp.json entirely or add it to disabledMcpjsonServers in settings.

OrchestKit ships .mcp.json with all servers disabled: false and settings.local.json with an enabledMcpjsonServers allowlist. No contradictions.

Per-Agent MCP Scoping (CC 2.1.49)

Agent frontmatter supports mcpServers to control which MCP servers a subagent can access:

---
name: web-research-analyst
mcpServers: [tavily]
---

• mcpServers omitted → agent inherits ALL MCP tools from parent session
• mcpServers: [tavily] → agent ONLY sees tavily tools
• mcpServers: [] → agent sees NO MCP tools

OrchestKit agents declare mcpServers explicitly to avoid inheriting unnecessary tool definitions into their smaller context windows (Sonnet: 128K vs Opus: 200K).

Background Agent Limitation

MCP tools are NOT available in background subagents. This is a hard CC platform limitation.

Agents spawned with run_in_background: true or background: true cannot call any MCP tools (tavily, context7, memory, sequential-thinking, agentation). Design background agents to use only built-in CC tools (Read, Grep, Glob, Bash, etc.).

If a background agent needs MCP tools, run it in the foreground instead.

Token Overhead & MCPSearch

Each connected MCP adds tool definitions to the context window:

MCPSearch (default since CC 2.1.7): When MCP tool schemas exceed 10% of the context window, CC automatically defers schema loading and uses an MCPSearch tool to discover tools on demand — reducing overhead by ~85%.

With 5 MCPs (~5.7K tokens = 2.8% of 200K), schemas load upfront. This is acceptable. If you add more MCPs and cross the 10% threshold, MCPSearch activates automatically.

Tighten the threshold: Set ENABLE_TOOL_SEARCH=auto:5 in your shell profile to defer at 5% instead of 10%.

Note: MCPSearch requires Sonnet 4+ or Opus 4+ — Haiku agents cannot use it and always get full schema overhead. OrchestKit's 2 Haiku agents (ci-cd-engineer, release-engineer) use mcpServers scoping to minimize their MCP exposure.

Enabling/Disabling MCPs

Edit .mcp.json and set "disabled": true or false for each MCP:

{
  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/mcp.schema.json",
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "disabled": false
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
      "disabled": false
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": { "MEMORY_FILE": ".claude/memory/memory.json" },
      "disabled": false
    },
    "tavily": {
      "command": "sh",
      "args": ["-c", "TAVILY_API_KEY=$(op read 'op://Private/Tavily API Key/API Key') exec npx -y tavily-mcp@latest"],
      "disabled": false
    },
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"],
      "disabled": false
    },
    "21st-dev-magic": {
      "command": "npx",
      "args": ["-y", "@21st-dev/magic@latest"],
      "env": { "API_KEY": "${TWENTYFIRST_DEV_API_KEY}" },
      "disabled": false
    }
  }
}

To disable a specific MCP, set "disabled": true in .mcp.json. Ensure settings.local.json does NOT have enableAllProjectMcpServers: true (which would override the disabled flag).

Tavily MCP

When TAVILY_API_KEY is set and the Tavily MCP is enabled, agents gain access to production-grade web research tools.

Tools

Which agents and skills use Tavily?

Setup

Option A: Local MCP with 1Password (recommended)

1. Get a free API key (1,000 credits/month): https://app.tavily.com
2. Store in 1Password: op item create --category "API Credential" --title "Tavily API Key" "API Key=tvly-..."
3. Use op read in .mcp.json (see example config above) — the sh -c wrapper fetches the key from 1Password at MCP startup

Note: Claude Code's MCP env block only resolves $\{ENV_VAR\} syntax, not op:// references directly. Use the sh -c "TAVILY_API_KEY=$(op read '...') exec npx ..." wrapper pattern to read from 1Password at startup.

Option B: Remote MCP (hosted, no npx)

Tavily offers a hosted MCP server — no local process needed. Generate the URL at https://app.tavily.com → "Remote MCP" → "Generate MCP Link":

"tavily": {
  "type": "url",
  "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=YOUR_KEY",
  "disabled": false
}

Without Tavily

Agents fall back to WebFetch (Haiku-summarized) → agent-browser (full headless). Tavily fills the middle tier with raw markdown extraction and semantic search.

MCP Dependencies

Plugin Integration

OrchestKit agents and skills integrate with these MCPs:

Without MCPs

Commands still work - MCPs just enhance them:

• /ork:implement works, but without latest library docs (context7)
• Web research works via WebFetch/WebSearch, but without raw markdown extraction (tavily)
• Session continuity works via local files and knowledge graph

Browser Automation

For browser automation and testing, use the agent-browser skill instead of an MCP. See the agent-browser skill for Vercel's headless browser CLI.

Presets

Preset Definitions

Complete (Default)

Everything enabled - full AI-assisted development.

{
  "preset": "complete",
  "skills": {
    "ai_ml": true,
    "backend": true,
    "frontend": true,
    "testing": true,
    "security": true,
    "devops": true,
    "planning": true
  },
  "agents": {
    "product": true,
    "technical": true
  },
  "hooks": {
    "safety": true,
    "productivity": true,
    "quality_gates": true,
    "team_coordination": true,
    "notifications": false
  },
  "commands": { "enabled": true },
  "mcps": {
    "context7": false,
    "sequential_thinking": false,
    "memory": false
  }
}

Standard

All skills, no agents (spawn manually).

{
  "preset": "standard",
  "skills": { "ai_ml": true, "backend": true, "frontend": true, "testing": true, "security": true, "devops": true, "planning": true },
  "agents": { "product": false, "technical": false },
  "hooks": { "safety": true, "productivity": true, "quality_gates": true, "team_coordination": true, "notifications": false },
  "commands": { "enabled": true },
  "mcps": { "context7": false, "sequential_thinking": false, "memory": false }
}

Lite

Essential skills only, minimal overhead.

{
  "preset": "lite",
  "skills": {
    "ai_ml": false,
    "backend": false,
    "frontend": false,
    "testing": true,
    "security": true,
    "devops": false,
    "planning": true
  },
  "agents": { "product": false, "technical": false },
  "hooks": {
    "safety": true,
    "productivity": true,
    "quality_gates": false,
    "team_coordination": false,
    "notifications": false
  },
  "commands": {
    "enabled": true,
    "disabled": ["add-golden", "implement", "fix-issue", "review-pr", "run-tests", "create-pr"]
  },
  "mcps": { "context7": false, "sequential_thinking": false, "memory": false }
}

Hooks-only

Just safety guardrails, no skills or agents.

{
  "preset": "hooks-only",
  "skills": {
    "ai_ml": false,
    "backend": false,
    "frontend": false,
    "testing": false,
    "security": false,
    "devops": false,
    "planning": false
  },
  "agents": { "product": false, "technical": false },
  "hooks": {
    "safety": true,
    "productivity": true,
    "quality_gates": false,
    "team_coordination": true,
    "notifications": false
  },
  "commands": { "enabled": false },
  "mcps": { "context7": false, "sequential_thinking": false, "memory": false }
}