Switchboard

MCP proxy that aggregates multiple child MCPs into suite tools with lazy subtool expansion. Presents one tool per MCP to the host, revealing subtools on demand. Typical token reduction: 85-90%. Memory MCP: 5,913 → 634 tokens (89%). Large MCPs like Supabase save 20,000+ tokens.

---

Installation

npm install -g @george5562/switchboard

Or use directly without installation:

npx @george5562/switchboard init

Requirements: Node.js v18+

---

Quick Start

1. Install:

npm install -g @george5562/switchboard

2. Initialize:

cd your-project
switchboard init

Migrates existing .mcp.json and creates .switchboard/mcps/[name]/.mcp.json for each MCP. Auto-populates descriptions for common MCPs.

3. Replace .mcp.json:

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "args": [],
      "env": {}
    }
  }
}

4. Restart MCP host (Claude Code, Cursor, etc.)

---

How It Works

Host ──JSON-RPC(stdio)──> Switchboard
                       └─spawn on demand──> Child MCPs (stdio)

1. Discovery: Finds child MCPs via .switchboard/mcps/*/.mcp.json
2. Aggregation: Creates one suite tool per child MCP
3. Lazy Loading: Spawns child processes only when needed
4. Routing: Forwards introspect and call actions to appropriate children

---

Features

• 85-90% token reduction through lazy subtool expansion
• Zero-config operation with sensible defaults
• Auto-migration via switchboard init
• Auto-populated descriptions for 50+ common MCPs
• Comprehensive test suite (15/15 passing)
• Built on official @modelcontextprotocol/sdk
• Lazy child MCP initialization
• Single suite tool per MCP presented to host

---

Documentation

Getting Started

• Quick Start
• Configuration

In-Depth Guides

• Architecture - System design and data flow
• Protocol Lessons - Insights from building a proxy MCP
• Troubleshooting - Solutions to common issues
• Best Practices - Guidelines for building robust MCPs

API Reference

Each suite tool accepts:

{
  action: "introspect" | "call",
  subtool?: string,     // Required for "call"
  args?: object         // Arguments for the subtool
}

Introspect - Discover available subtools:

{
  action: 'introspect';
}
// Returns: [{ name: "click", summary: "Click element", inputSchema: {...} }, ...]

Call - Execute a specific subtool:

{
  action: "call",
  subtool: "click",
  args: { selector: "#button" }
}
// Returns: (result from child MCP)

---

Roadmap

v0.2.0: Multi-Location Support

Support .cursor/.mcp.json, .gemini/.mcp.json, and other IDE-specific locations. Single command discovers MCPs across all locations with auto-detection.

# Future API
switchboard init --cursor    # Migrates .cursor/.mcp.json
switchboard init --gemini    # Migrates .gemini/.mcp.json
switchboard init --all       # Discovers all configs

v0.3.0: Intermediate Tier Grouping

Group tools by functionality within large MCPs to reduce context for MCPs with 50+ tools.

Before (current):
Host sees: supabase_suite → 60 tools on introspect

After (v0.3.0):
Host sees: supabase_suite → 5 groups on introspect
  - supabase_read_group → 15 read operations
  - supabase_write_group → 12 write operations
  - supabase_auth_group → 8 auth operations
  ...

• ML-based automatic clustering
• Manual group overrides in config
• 3-tier hierarchy: suite → groups → tools
• 60-80% further token reduction

# Future API
switchboard analyze supabase_suite  # Suggests tool groupings
switchboard group supabase_suite    # Auto-creates groups

v0.4.0: Dynamic MCP Discovery

On-demand MCP loading from a global registry. Integration with 1MCP:

LLM requests database functionality
  ↓
Switchboard Index returns database-related MCP suites
  ↓
LLM selects supabase_suite
  ↓
Switchboard downloads, spawns, and connects Supabase MCP
  ↓
LLM uses Supabase tools

• Curated index of 100+ MCPs by use case
• Decision tree navigation
• Just-in-time installation via npx
• Automatic cleanup of unused MCPs
• Security sandboxing and signature validation

# Future API
switchboard index           # Browse available MCPs
switchboard discover        # Enable dynamic discovery mode
switchboard install github  # Pre-install common MCPs

Flow:

1. Host loads switchboard_index
2. LLM introspects database MCPs
3. Switchboard returns [supabase, postgres, mongodb, ...]
4. LLM calls { action: "load", mcp: "supabase" }
5. Switchboard spawns Supabase MCP and returns supabase_suite
6. LLM uses tools

v0.5.0+: Advanced Features

• MCP health monitoring
• Performance analytics and token tracking
• Smart response caching
• Multi-host support
• Plugin system

---

Testing

Run Tests

npm test           # Full test suite
npm run test:unit  # Unit tests only
npm run test:e2e   # End-to-end tests

Test Coverage

✓ Unit Tests: 10/10 passing
  - Config loading and validation
  - Description summarization
  - Protocol framing

✓ E2E Tests: 5/5 passing
  - Full JSON-RPC workflow
  - Child MCP integration
  - Suite tool functionality

Performance Benchmarks

• Startup: ~1000ms (includes child discovery)
• Tool Listing: ~immediate (cached)
• Child Operations: ~2000ms (spawn + RPC)
• Token Reduction:
  • Memory MCP: 89% (5,913 → 634 tokens)
  • Typical aggregate: 85-90% (1,820+ → 200-300 tokens)
  • Large MCPs like Supabase: 95%+ (20,000+ → ~1,000 tokens)

---

Development

Project Structure

src/
├── index.ts              # Main entrypoint
├── cli/init.ts           # Init command implementation
├── core/
│   ├── config.ts         # Load/validate config
│   ├── registry.ts       # Discover child MCPs
│   ├── child.ts          # Spawn child MCP; JSON-RPC client
│   ├── router.ts         # tools/list + tools/call logic
│   └── summarise.ts      # Shrink descriptions

Scripts

npm run build        # Build with esbuild
npm run dev          # Development with ts-node
npm run test         # Run all tests
npm run lint         # ESLint
npm run format       # Prettier

Contributing

1. Fork and create feature branch
2. Make changes and add tests
3. Ensure tests pass: npm test
4. Update docs if needed
5. Submit pull request

Use Conventional Commits: feat:, fix:, docs:, test:

---

License

MIT © George Stephens

---

Links

• npm: https://www.npmjs.com/package/@george5562/switchboard
• GitHub: https://github.com/George5562/Switchboard
• Issues: https://github.com/George5562/Switchboard/issues
• Changelog: CHANGELOG.md

---

Acknowledgments

Built with:

• @modelcontextprotocol/sdk - Official MCP SDK
• esbuild - Fast bundler
• zod - TypeScript schema validation

---

Switchboard transforms MCP from a tool flooding problem into a token-efficient aggregation layer.