MCP Conductor

The canonical MCP hub for any agent platform. 99.7% fewer tokens. One npx command.

MCP Conductor is a single MCP server that orchestrates all your other MCP servers through a sandboxed Deno runtime. Works with Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex CLI, Cline, Zed, Continue.dev, OpenCode, and Kimi Code. Instead of your AI client making direct tool calls (and dumping every intermediate result into your context window), it writes TypeScript code that runs in an isolated sandbox. Only the final result comes back.

Before: 153,900 tokens → AI client context window → 153,900 tokens billed
After:  153,900 tokens → Deno sandbox → 435 tokens → AI client context window

Average measured reduction: 99.7%. Verified against Anthropic's published benchmarks.

Quick Install

v3.1.1 — Supported Clients

| Client | Config path (macOS) | Config path (Linux) | Config path (Windows) | |---|---|---|---| | Claude Code | ~/.claude/settings.json | ~/.claude/settings.json | %APPDATA%\Claude Code\claude_code_config.json | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | ~/.config/claude/claude_desktop_config.json | %APPDATA%\Claude\claude_desktop_config.json | | Cursor | ~/.cursor/mcp.json | ~/.cursor/mcp.json | ~/.cursor/mcp.json | | Gemini CLI | ~/.gemini/settings.json | ~/.gemini/settings.json | ~/.gemini/settings.json | | Codex CLI | ~/.codex/config.toml | ~/.codex/config.toml | ~/.codex/config.toml | | Cline | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json | | Zed | ~/Library/Application Support/Zed/settings.json | ~/.config/zed/settings.json | %LOCALAPPDATA%\Zed\settings.json | | Continue.dev | ~/.continue/config.yaml | ~/.continue/config.yaml | ~/.continue/config.yaml | | OpenCode | ~/.config/opencode/opencode.json | ~/.config/opencode/opencode.json | %APPDATA%\opencode\opencode.json | | Kimi Code | ~/Library/Application Support/Kimi Code/mcp_settings.json | ~/.config/kimi-code/mcp_settings.json | %APPDATA%\Kimi Code\mcp_settings.json |

Guided Setup (recommended)

The setup wizard auto-detects every supported client on your machine and offers per-client consolidation:

npx -y @darkiceinteractive/mcp-conductor-cli@next setup

See What the wizard does below.

Manual Config Snippets

Paste the appropriate block into your client's config file. The wizard does this automatically.

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "mcp-conductor": {
      "command": "npx",
      "args": ["-y", "@darkiceinteractive/mcp-conductor"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-conductor": {
      "command": "npx",
      "args": ["-y", "@darkiceinteractive/mcp-conductor"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-conductor": {
      "command": "npx",
      "args": ["-y", "@darkiceinteractive/mcp-conductor"]
    }
  }
}

For Codex CLI (TOML), Continue.dev (YAML), and other formats, use mcp-conductor-cli export --client <id> — see Multi-client export.

Restart your AI tool after editing the config. That's it.

What the Wizard Does

Running npx -y @darkiceinteractive/mcp-conductor-cli@next setup steps through the following for each detected client:

1. Scan — discovers all 10 client config locations on your machine (global and project-local).
2. Diff — for each existing config, parses the current server list and shows what will move.
3. Confirm per-client — prompts once per client; you can skip any client individually.
4. Write conductor config — merges your existing servers into ~/.mcp-conductor.json and installs the conductor entry back into the client config.
5. Backup originals — creates a timestamped .bak.YYYYMMDDHHMMSS copy of every config file before modifying it.

In non-interactive environments (CI, piped stdin) the wizard proceeds automatically with safe defaults.

Verifying Setup

mcp-conductor-cli doctor

The doctor command runs a health check across all configured servers and prints an MCP CLIENT COVERAGE section showing every detected client config with an [OK] or [MISSING] status for the conductor entry.

MCP CLIENT COVERAGE
  [OK]      Claude Code        ~/.claude/settings.json
  [OK]      Claude Desktop     ~/Library/Application Support/Claude/claude_desktop_config.json
  [OK]      Cursor             ~/.cursor/mcp.json
  [MISSING] Zed                ~/Library/Application Support/Zed/settings.json

Run npx -y @darkiceinteractive/mcp-conductor-cli@next setup to install the conductor entry in any [MISSING] client.

Multi-client Export

Generate a ready-to-paste config snippet for any supported client:

# Codex CLI — writes TOML
mcp-conductor-cli export --client codex

# Continue.dev — writes YAML
mcp-conductor-cli export --client continue

# Claude Desktop — writes JSON (default)
mcp-conductor-cli export --client claude-desktop

The exported file is written to the current directory as <client>-config.<ext>. Pass --output <path> to override.

Full client setup documentation is at docs.darkice.co/setup/clients.

30-Second Example

// Your AI client writes this code, which runs inside the Deno sandbox
const [issues, files] = await mcp.batch([
  () => mcp.server('github').call('list_issues', { owner: 'myorg', repo: 'myrepo', state: 'open' }),
  () => mcp.server('filesystem').call('list_directory', { path: '/src' })
]);

return {
  openBugs: issues.filter(i => i.labels.some(l => l.name === 'bug')).length,
  tsFiles: files.filter(f => f.name.endsWith('.ts')).length
};
// Returns: {"openBugs": 12, "tsFiles": 47}  ←  under 100 tokens

Why It Matters

When an AI client calls MCP tools directly, every response lands in the context window — raw JSON, file metadata, pagination objects, fields you never asked for. A single GitHub list_issues call can return 40,000+ tokens. If you're making 10 calls per task, that's 400,000 tokens before the model has written a single line of code.

MCP Conductor flips the model: the client writes TypeScript code that processes the tool responses inside a Deno sandbox. The sandbox can call any connected MCP server, filter and aggregate the results, and return only the compact summary. Your context window stays small. Your costs stay low.

| Scenario | Without Conductor | With Conductor | Reduction | |---|---|---|---| | 300-document Drive pipeline | 153,900 tokens | 435 tokens | 99.72% | | GitHub issues triage (10 repos) | ~400,000 tokens | ~2,000 tokens | 99.5% | | Web research (5 searches) | ~50,000 tokens | ~800 tokens | 98.4% |

v3 Highlights

| Feature | What it does | Docs | |---|---|---| | Tool Registry | Schema validation, hot-reload, type generation | Architecture | | Response Cache | LRU + CBOR serialisation, TTL per tool | Configuration | | Reliability Gateway | Timeout, retry, circuit breaker | Architecture | | Connection Pool | Warm sandbox pool, persistent server connections | Configuration | | Sandbox API | compact, summarize, findTool, budget | Sandbox API | | Daemon Mode | Shared KV store, distributed lock | Configuration | | Observability | Cost predictor, hot-path profiler, session replay | Architecture | | Passthrough Adapter | Expose backend tools directly (X1) | Recipes | | Lifecycle Tools + CLI | import_servers_from_claude, setup wizard (X2) | Sandbox API | | PII Tokenisation | Built-in redaction matchers (X4) | Configuration |

v3.1.1 Additions

| Feature | What it does | |---|---| | Multi-client adapters | Read and write configs for all 10 supported clients | | Setup wizard (MC3) | Interactive per-client consolidation with backups | | Per-client export (MC4) | export --client <id> writes the correct format (JSON / TOML / YAML) | | Doctor client coverage (MC5) | doctor reports [OK] / [MISSING] per detected client config |

Migrating from v2? See the migration guide.

Token-Savings Reporter

Pass show_token_savings: true on any execute_code call to see a breakdown:

{
  "result": { "processed": 300, "with_dates": 287 },
  "tokenSavings": {
    "estimatedPassthroughTokens": 153900,
    "actualExecutionTokens": 435,
    "tokensSaved": 153465,
    "savingsPercent": 99.72
  }
}

Or enable it globally in ~/.mcp-conductor.json:

{
  "metrics": {
    "alwaysShowTokenSavings": true
  }
}

Session totals are always available via get_metrics.

Docs

Full documentation at https://docs.darkice.co — deploys at D4. In the meantime, all reference material is in docs/v3/.

| Guide | Description | |-------|-------------| | Architecture | System design and data flow | | Configuration | All config options | | Sandbox API | The mcp object inside execute_code | | Recipes | Practical patterns and examples | | Migration (v2 → v3) | Breaking changes and migration steps | | Client Setup | Per-client config reference for all 10 supported clients |

CLI Quick-Start

# Guided multi-client setup — detects all supported client configs automatically
npx -y @darkiceinteractive/mcp-conductor-cli@next setup

# Health check with client coverage report
mcp-conductor-cli doctor

# Export config for a specific client (TOML for Codex, YAML for Continue, etc.)
mcp-conductor-cli export --client <client-id>

# Check system requirements (Node, Deno, conductor config)
mcp-conductor-cli check

# Show current configuration status
mcp-conductor-cli status

# Enable exclusive mode (routes all MCP calls through the sandbox)
mcp-conductor-cli enable-exclusive [--dry-run]

# Add a backend server
mcp-conductor-cli config add github npx -- -y @modelcontextprotocol/server-github

Contributing

Contributions welcome. Please read CONTRIBUTING.md for guidelines.

• Bug reports: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md

Licence

MIT — see LICENSE

Built by DarkIce Interactive · @darkiceinteractive/mcp-conductor on npm