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