MCP Conductor

An MCP server that orchestrates code execution in a sandboxed Deno environment with access to all your MCP servers as APIs. Instead of Claude making direct tool calls (high token usage), Claude writes code that runs in a sandboxed environment. Intermediate data stays in the sandbox; only compact results return to Claude's context.

Key Benefits:

• 90-98% token reduction for complex workflows
• Sub-second overhead for code execution
• Works with any MCP server
• Secure Deno sandbox with minimal permissions

Requirements

• Node.js 18+ - JavaScript runtime
• Deno 1.40+ - Secure sandbox runtime (install from https://deno.land)

Installation

Quick Start (npm - Recommended)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop - that's it! The package auto-downloads on first use.

Prerequisite: Deno must be installed for the sandbox runtime.

Alternative: From Source

For development or customisation:

git clone https://github.com/darkiceinteractive/mcp-conductor.git
cd mcp-conductor
npm run setup
node dist/bin/cli.js enable-exclusive

The enable-exclusive command migrates your existing MCP servers to a conductor-managed config, ensuring Claude must use execute_code for all MCP operations. This provides maximum token savings (90%+).

Manual Configuration

If not using npx, add to Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-conductor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-conductor/dist/index.js"]
    }
  }
}

Important: Replace /absolute/path/to/mcp-conductor with the actual path where you cloned the repository.

Or use the CLI to add it automatically:

node dist/bin/cli.js init

Step 3: Restart Claude Desktop

Restart Claude Desktop to load the new server. You should see "mcp-conductor" in the MCP servers list.

Usage

In Claude, you can now use the execute_code tool:

// List files and count by type
const fs = mcp.server('filesystem');
const files = await fs.call('list_directory', { path: '/project/src' });
const counts = { ts: 0, js: 0, other: 0 };
for (const f of files.entries) {
  if (f.name.endsWith('.ts')) counts.ts++;
  else if (f.name.endsWith('.js')) counts.js++;
  else counts.other++;
}
return counts;

CLI Commands

Run from the project directory:

# Check system requirements
node dist/bin/cli.js check

# Show configuration status
node dist/bin/cli.js status

# Add to Claude Desktop config automatically
node dist/bin/cli.js init [--dry-run]

# Start the server manually (usually not needed - Claude Desktop starts it)
node dist/bin/cli.js serve [options]

Serve Options

node dist/bin/cli.js serve \
  --port 0 \             # Bridge port (0 = dynamic allocation, default)
  --mode execution \     # Mode: execution|passthrough|hybrid
  --timeout 30000 \      # Default timeout in ms
  --verbose              # Enable debug logging

Note: Port 0 (the default) enables dynamic port allocation, allowing multiple instances of MCP Conductor to run simultaneously without port conflicts.

Exclusive Mode Commands

Exclusive mode ensures Claude ONLY sees mcp-conductor, forcing all MCP operations through execute_code for maximum token savings.

# Enable exclusive mode (recommended)
# Migrates servers from Claude config to ~/.mcp-conductor.json
node dist/bin/cli.js enable-exclusive [--dry-run]

# Disable exclusive mode
# Restores servers back to Claude config
node dist/bin/cli.js disable-exclusive [--dry-run]

# View current configuration status
node dist/bin/cli.js config show

# List servers in conductor config
node dist/bin/cli.js config servers

# Add a server to conductor config
node dist/bin/cli.js config add <name> <command> [args...]

# Remove a server from conductor config
node dist/bin/cli.js config remove <name>

Permissions Commands

Manage Claude Code MCP tool permissions to auto-allow all discovered tools:

# List currently configured MCP permissions in your settings
node dist/bin/cli.js permissions list

# Discover all available MCP tools and show new permissions needed
node dist/bin/cli.js permissions discover --new-only

# Show as JSON (for manual copying)
node dist/bin/cli.js permissions discover --json

# Preview what would be added to settings
node dist/bin/cli.js permissions add --dry-run

# Add all new permissions to user settings (~/.claude/settings.json)
node dist/bin/cli.js permissions add

# Add to project settings instead (.claude/settings.json)
node dist/bin/cli.js permissions add --scope project

This solves the common issue of seeing permission prompts for MCP tools. Run permissions add once to auto-approve all tools from your configured MCP servers.

Project Instructions

Install project-level instructions to teach Claude to use execute_code for batch operations:

# Install CLAUDE.md to a project directory
node dist/bin/cli.js install-instructions --dir /path/to/project

# Append to existing CLAUDE.md
node dist/bin/cli.js install-instructions --append

# Preview what would be created
node dist/bin/cli.js install-instructions --dry-run

This creates a CLAUDE.md file that instructs Claude to prefer execute_code for multi-step MCP operations, ensuring token savings across all your projects.

MCP Tools

execute_code

Execute TypeScript/JavaScript code in a sandboxed Deno environment.

// Access MCP servers
const github = mcp.server('github');
const result = await github.call('search_repos', { query: 'ai' });

// Or use attribute-style access
const result = await mcp.github.call('search_repos', { query: 'ai' });

// Search for tools
const tools = await mcp.searchTools('file');

// Log (captured in response)
mcp.log('Processing...');

// Report progress (for streaming)
mcp.progress(50, 'Halfway done');

// Smart batching with auto rate limit detection
const results = await mcp.batch([
  { server: 'github', tool: 'search_repositories', params: { query: 'ai' } },
  { server: 'github', tool: 'search_repositories', params: { query: 'ml' } },
]);

// Convenience method for batched web searches (requires brave-search)
const searchResults = await mcp.batchSearch([
  'query 1',
  'query 2',
  'query 3'
], { topN: 3 });

list_servers

List all connected MCP servers and their tools.

discover_tools

Search for tools across all servers.

get_metrics

Get session metrics including token savings.

set_mode

Switch between operation modes:

• execution - All requests go through code executor (default, maximum token savings)
• passthrough - Direct tool calls without code execution (for debugging)
• hybrid - Automatic selection based on task complexity

compare_modes

Analyse how a task would be handled in different modes.

reload_servers

Reload MCP server configurations (useful after editing claude_desktop_config.json).

passthrough_call

Make direct tool calls without code execution. Note: This tool has high token cost and should only be used for debugging.

add_server

Add an MCP server to conductor config at runtime without restarting Claude.

remove_server

Remove an MCP server from conductor config at runtime.

update_server

Update an existing server's configuration (command, args, or environment variables) without removing and re-adding it. Useful for updating API keys after upgrading a service plan.

// Update API key for brave-search after upgrading plan
mcp__mcp-conductor__update_server({
  name: 'brave-search',
  env: { BRAVE_API_KEY: 'your-new-api-key' }
})

Optional: Web Search Optimisation

For projects requiring multiple web searches, you can add brave-search MCP server for batched, parallel searches via execute_code.

Setup

1. Get a free Brave Search API key (2000 queries/month): https://brave.com/search/api/

2. Add to your conductor config:

   node dist/bin/cli.js config add brave-search npx -y @modelcontextprotocol/server-brave-search

3. Set the API key in ~/.mcp-conductor.json:

   {
     "servers": {
       "brave-search": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-brave-search"],
         "env": {
           "BRAVE_API_KEY": "your-api-key-here"
         }
       }
     }
   }

4. Restart Claude to reload servers.

Usage

With brave-search configured, use mcp.batchSearch() for automatic rate limit handling:

// Simple: handles rate limits automatically, parses results
const results = await mcp.batchSearch([
  'TypeScript best practices',
  'React hooks tutorial',
  'Node.js performance tips'
], { topN: 3 });

return results;
// Returns: { "TypeScript...": [{title, url, description}, ...], ... }

How it works:

• Attempts parallel execution first (fastest)
• Auto-detects rate limits from API errors
• Falls back to sequential with 1.1s delays if rate limited
• Logs warnings with upgrade guidance when rate limited
• Parses text responses into structured data

Rate limit warnings:

⚠️  RATE LIMITED: brave-search - Free tier limit hit. Retrying with delays...
💡 TIP: Upgrade your API plan for parallel execution: https://brave.com/search/api/

Benefits:

• No manual rate limit handling needed
• Parallel when possible, sequential when required
• 80%+ token savings vs native WebSearch

Upgrading Your Plan

After upgrading your Brave Search API plan:

1. Update the API key (no restart needed):

   mcp__mcp-conductor__update_server({
     name: 'brave-search',
     env: { BRAVE_API_KEY: 'your-new-api-key' }
   })

2. Test parallel mode with forceParallel:

   const results = await mcp.batchSearch([
     'query 1', 'query 2', 'query 3', 'query 4', 'query 5'
   ], { topN: 3, forceParallel: true });

3. If parallel works, it will be used automatically for all subsequent batches

Configuration

Exclusive Mode (Recommended)

In exclusive mode, Claude only sees mcp-conductor and must use execute_code for all MCP operations. This provides:

• Maximum token savings (90-98% reduction)
• No bypass possible - Claude cannot make direct MCP calls
• No CLAUDE.md required - Works automatically in any project

How it works:

Before (default):                    After (exclusive mode):
┌─────────────────────────────┐     ┌─────────────────────────────┐
│ Claude's Config             │     │ Claude's Config             │
│ ├── mcp-conductor           │     │ └── mcp-conductor ← ONLY    │
│ ├── github ← Claude sees    │     └─────────────────────────────┘
│ ├── filesystem ← can bypass │     ┌─────────────────────────────┐
│ └── other servers...        │     │ ~/.mcp-conductor.json       │
└─────────────────────────────┘     │ ├── github ← hidden         │
                                    │ ├── filesystem ← hidden     │
                                    │ └── other servers...        │
                                    └─────────────────────────────┘

Enable exclusive mode:

node dist/bin/cli.js enable-exclusive

Environment Variables

MCP_CONDUCTOR_PORT=0             # Bridge port (0 = dynamic allocation)
MCP_CONDUCTOR_MODE=execution     # Operation mode
MCP_CONDUCTOR_TIMEOUT=30000      # Default timeout in ms
MCP_CONDUCTOR_LOG_LEVEL=info     # Log level: debug|info|warn|error

Programmatic Configuration

import { MCPConductorServer, loadConfig } from '@darkiceinteractive/mcp-conductor';

const config = loadConfig();
const server = new MCPConductorServer(config);
await server.start();

Security

The Deno sandbox is configured with minimal permissions:

• Network access only to localhost bridge
• No filesystem access (except via MCP)
• No environment variable access
• No subprocess spawning
• Memory limits via V8 flags

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests once (no watch)
npm run test:run

# Run with coverage
npm run test:coverage

# Development mode (watch)
npm run dev

# Lint
npm run lint

# Format
npm run format

Distribution

Publishing to npm

1. Update version in package.json
2. Build and test:

   npm run build
   npm run test:run

3. Publish:

   npm publish --access public

Creating a GitHub Release

1. Tag the release:

   git tag v0.1.0
   git push origin v0.1.0

2. Create a release on GitHub with the changelog

Local Development with Claude Desktop

For local development, point Claude Desktop to your development build:

{
  "mcpServers": {
    "mcp-conductor": {
      "command": "node",
      "args": ["/Users/you/Dev/mcp-conductor/dist/index.js"]
    }
  }
}

Architecture

Claude Code → MCP Conductor → HTTP Bridge → Deno Sandbox
                                  ↓
                          Connected MCP Servers

1. Claude calls execute_code with TypeScript code
2. Code is wrapped and run in isolated Deno subprocess
3. Sandbox calls HTTP bridge to invoke MCP tools
4. Only the final return value goes back to Claude

Documentation

Detailed documentation is available in the docs folder:

| Document | Description | |----------|-------------| | Architecture | Internal design and data flow | | Configuration | All configuration options | | CLI Reference | Command-line interface | | Tools Reference | MCP tools and the mcp API | | Permissions | Managing Claude Code permissions | | Troubleshooting | Common issues and solutions |

Troubleshooting

"Deno not installed"

Install Deno from https://deno.land or use:

brew install deno  # macOS

"Network access denied"

The Deno sandbox only allows access to the localhost bridge. Ensure your MCP servers are accessible through the bridge.

"Timeout exceeded"

Increase the timeout for long-running operations:

// In execute_code call
{ timeout_ms: 60000 }

"Server not found"

Check that your MCP server is:

1. Listed in claude_desktop_config.json
2. Properly started and connected
3. Use list_servers to verify

Licence

MIT

Contributing

Contributions welcome! Please read our contributing guidelines and submit PRs to the GitHub repository.