switchboard-mcp 0.1.0

Intelligent multi-provider agent routing MCP server — transparently switch between AI providers and models

Switchboard 🎛️

Never let your AI coding agent hit a dead end again.

A multi-provider AI routing layer that gives any MCP-compatible coding agent (Claude Code, Cursor, Windsurf) unlimited flow by transparently switching between AI providers when rate limits hit or when a better model exists for the task.

---

The Problem

It's 2am. You're deep in a coding session with Claude Code. You've got 80 messages of context, the agent is about to write the perfect solution — and then:

"You've reached your message limit. Please upgrade your plan or wait."

The agent stops dead. Your flow is gone. You're staring at an error message instead of working code.

This shouldn't happen. Your coding agent should never hit a wall because one provider said no.

Switchboard fixes this. It sits between your coding agent and the AI providers, watching for rate limits, picking the best model for each task, and silently falling back to alternatives — all without the agent (or you) ever knowing a switch happened.

---

How It Works

┌──────────────────────────────────────────────────────────────────┐
│                    YOUR WORKSTATION                               │
│                                                                  │
│  ┌─────────────┐                                                 │
│  │ Your Agent  │   Claude Code / Cursor / Windsurf               │
│  │ (Claude etc)│                                                 │
│  └──────┬──────┘                                                 │
│         │  MCP tool calls only                                    │
│         ▼                                                        │
│  ┌──────────────────────────────────────────────────────┐        │
│  │           SWITCHBOARD (The Whisperer)                 │        │
│  │                                                      │        │
│  │  ┌──────────┐   ┌───────────┐   ┌──────────────┐    │        │
│  │  │ Layer 1  │──▶│  Layer 2  │──▶│   Fallback   │    │        │
│  │  │ Rules    │   │ Classifier│   │   Chain      │    │        │
│  │  │ (fast)   │   │ (DistilBERT)│  │ + Health     │    │        │
│  │  └──────────┘   └───────────┘   └──────┬───────┘    │        │
│  │                                        │             │        │
│  │  ┌──────────────────────────────────┐  │             │        │
│  │  │ Context Serializer (Handoff)     │──┘             │        │
│  │  │ Structured state ≠ raw history   │                │        │
│  │  └──────────────────────────────────┘                │        │
│  └───────────────────────┬──────────────────────────────┘        │
│                          │                                       │
│         ┌────────────────┼────────────────┐                     │
│         ▼                ▼                ▼                     │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐                  │
│  │ Anthropic│    │OpenRouter│    │ Direct   │                  │
│  │ (Claude) │    │(14 models│    │ APIs     │                  │
│  └──────────┘    └──────────┘    └──────────┘                  │
└──────────────────────────────────────────────────────────────────┘

Routing Decision Flow

Request arrives at Switchboard
       │
       ▼
┌──────────────────┐
│  Layer 1: Rules  │  ← Checks in order:
│  (instant)       │     1. User preferences (cheap/fast)?
└────────┬─────────┘     2. Context > 60K tokens?
         │                3. Simple task (explain, autocomplete)?
    conclusive?           4. Latency-sensitive?
         │                5. Budget cap?
    ┌────┴────┐
    │         │
   YES        NO
    │         │
    ▼         ▼
 Route to   ┌──────────────────┐
 chosen     │ Layer 2:         │  ← Hybrid classifier:
 model      │ Classifier       │     60% semantic (sentence-transformers)
            │ (all-MiniLM-L6)  │     40% keyword overlap
            └────────┬─────────┘
                     │
                     ▼
              Best model for task category
                     │
                     ▼
            ┌──────────────────┐
            │  Fallback Chain  │  ← If model fails:
            │  (health-aware)  │     1. Try next in priority list
            └────────┬─────────┘     2. Skip degraded/rate-limited
                     │               3. Fall to free-tier models
                     ▼               4. Never hard-stop
              Response back to agent
              (switch is invisible)

---

Quick Start

Install

pip install switchboard-mcp

Set your API keys

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENROUTER_API_KEY="sk-or-..."

Add to your MCP client

Every MCP client speaks the same stdio transport protocol. Your server runs as a subprocess, the client connects, discovers the 4 tools, and starts calling them. Switchboard is completely client-agnostic.

The core config block is always the same — just the root key changes per client:

{
  "command": "switchboard",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "OPENROUTER_API_KEY": "sk-or-..."
  }
}

Here's exactly where it goes for each client. Find yours, copy, paste.

---

Client Configuration Reference

Client	Config File / Location	Root Key	Notes
Cursor	~/.cursor/mcp.json	"mcpServers"	Or via GUI: Settings → Features → MCP
VS Code (Copilot)	.vscode/mcp.json	"servers"	Workspace-level
Claude Code	~/.claude/settings.json	"mcpServers"	Global
Windsurf	Settings → MCP Servers	"mcpServers"	Same JSON structure as Cursor
JetBrains	Settings → AI Assistant → MCP	"mcpServers"	GUI paste or auto-configure
Antigravity / Google ADK	CLI config	stdio	One config, multiple agents
GitKraken	MCP settings	"mcpServers"	Same as Cursor

---

Cursor

File: ~/.cursor/mcp.json (or Settings → Features → MCP → Add Server)

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Restart Cursor. Your agent now has unlimited flow.

VS Code (Copilot)

File: .vscode/mcp.json (workspace-level)

Note: VS Code uses "servers" as the root key, not "mcpServers".

{
  "servers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Reload the window (Ctrl+Shift+P → "Developer: Reload Window").

Claude Code

File: ~/.claude/settings.json

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Next claude invocation picks it up automatically.

Windsurf

Location: Settings → MCP Servers → Add Server

Use the same JSON structure as Cursor:

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

JetBrains

Location: Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → "As JSON ChatForest"

Paste this config:

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Tip: JetBrains can also auto-configure external clients from the IDE side. If you're already using other MCP servers, just add Switchboard alongside them.

Antigravity / Google ADK

Uses the same stdio config. Configure once, use across multiple agents:

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

GitKraken

Location: MCP Settings → Add Server

Same JSON structure as Cursor:

{
  "mcpServers": {
    "switchboard": {
      "command": "switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

---

Using a Virtual Environment

If switchboard isn't on your PATH (you installed from source or in a venv), use the full path:

{
  "mcpServers": {
    "switchboard": {
      "command": "/path/to/your/venv/bin/switchboard",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Or with python -m:

{
  "mcpServers": {
    "switchboard": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/switchboard/package",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

That's it. Your agent now has unlimited flow. When Claude hits a rate limit, Switchboard silently routes to DeepSeek, GPT-4o, or Gemini — your agent never knows.

---

Model Registry

14 models across 3 tiers, from premium to free fallback:

Model	Provider	Cost/1K	Context	Best For	Tier
claude-sonnet-4	Anthropic	$0.003	200K	code gen, review, arch	Paid
claude-opus-4	Anthropic	$0.015	200K	review, security, arch	Paid
claude-haiku-3.5	Anthropic	$0.0008	200K	explanation, autocomplete	Paid
claude-sonnet-4	OpenRouter	$0.003	200K	code gen, review	Paid
deepseek-v3	OpenRouter	$0.00014	128K	code gen, debugging	Paid
deepseek-r1	OpenRouter	$0.0005	128K	debugging, review	Paid
gpt-4o	OpenRouter	$0.0025	128K	code gen, review	Paid
gpt-4o-mini	OpenRouter	$0.00015	128K	autocomplete, explanation	Paid
o3-mini	OpenRouter	$0.0011	200K	debugging, code gen	Paid
gemini-1.5-pro	OpenRouter	$0.00125	2M	code gen, architecture	Paid
gemini-2.0-flash	OpenRouter	$0.0001	1M	explanation, autocomplete	Paid
qwen-2.5-coder	OpenRouter	$0.00018	128K	code gen, autocomplete	Paid
llama-3.3-70b:free	OpenRouter	$0	128K	explanation, autocomplete	Free
qwen-2.5-72b:free	OpenRouter	$0	32K	explanation, autocomplete	Free

Full definitions in config/models.yaml. Add your own models by editing this file.

---

Routing Logic

Hybrid Approach: Rules First, Classifier Second

Layer 1 (Rule Engine) runs in < 1ms. It checks:

Signal	Action
prefer_cheap is set	Route to cheapest available model
prefer_fast is set	Route to fastest available model
Context > 60K tokens	Route to large-window model (Gemini 1.5 Pro: 2M)
Simple task keywords (explain, autocomplete, rename)	Route to cheapest model
Latency-sensitive (autocomplete, suggest, stream)	Route to fast model
max_cost_per_request budget	Filter to affordable models

Layer 2 (Classifier) runs when rules are inconclusive. A sentence-transformer (all-MiniLM-L6-v2, 22MB) classifies the task into 7 categories and picks the best model for that task type:

Category	Preferred Models
code_generation	Sonnet, DeepSeek-V3, GPT-4o
code_review	Opus, GPT-5
debugging	DeepSeek-R1, o3-mini
explanation	Haiku, Gemini Flash
architecture	Opus, GPT-5
autocomplete	Haiku, GPT-4o-mini, Qwen-Coder
security_audit	Opus, GPT-5

Fallback Priority

When a model fails, Switchboard walks down this chain:

1. claude-sonnet-4 (Anthropic direct)
2. anthropic/claude-sonnet-4 (OpenRouter)
3. deepseek/deepseek-v3
4. openai/gpt-4o
5. google/gemini-1.5-pro
6. qwen/qwen-2.5-coder-32b-instruct
7. meta-llama/llama-3.3-70b-instruct:free ← free tier
8. qwen/qwen-2.5-72b-instruct:free ← free tier (final safety net)

The agent NEVER hard-stops. Steps 7-8 are always free.

---

Context Serialization: Why This Isn't LiteLLM

When you switch models mid-conversation, most routers just forward the entire message history. That's wasteful and often breaks things (different models have different context windows and system prompt expectations).

Switchboard maintains a structured ConversationState:

GOAL: Build a REST API for a todo app
ACTIVE FILES:
  - app/main.py
  - app/models.py
CHANGES MADE SO FAR:
  + Added FastAPI setup
  + Created Todo model
KEY DECISIONS:
  - Used SQLite for persistence
CURRENT SUBTASK: Add authentication
Recent conversation:
[user]: Add JWT authentication
[assistant]: I'll add middleware...

This handoff prompt is 60-90% smaller than forwarding raw history, and the new model gets everything it actually needs to continue.

---

Configuration

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Recommended	Direct access to Claude models
OPENROUTER_API_KEY	Recommended	Access to 12+ models via OpenRouter
OPENAI_API_KEY	Optional	Future direct OpenAI support

Runtime Preferences

Set at runtime via set_routing_preferences:

{
  "prefer_cheap": true,
  "prefer_fast": false,
  "max_cost_per_request": 0.50,
  "blacklist_providers": ["openrouter"]
}

Customizing Models

Edit config/models.yaml to add models or adjust costs:

models:
  - id: your/custom-model
    provider: openrouter
    cost_per_1k_tokens: 0.001
    context_window: 128000
    strengths: [code_generation, debugging]
    speed: fast
    tier: paid

Logs

All routing decisions are logged to ~/.switchboard/routing.log in JSONL format:

tail -f ~/.switchboard/routing.log | jq .

Dry Run

See what Switchboard would do without making any API calls:

switchboard --dry-run

Or via CLI tester:

python cli_test.py dry_run

---

CLI Tester

The CLI tester demonstrates every routing scenario with beautiful Rich-formatted output. No API keys needed — all HTTP is mocked.

pip install switchboard-mcp[dev]
python cli_test.py dry_run

Available Scenarios

Command	What It Shows
python cli_test.py dry_run	All 7 task categories routed — zero API keys
python cli_test.py task_routing	Full routing table with classifications
python cli_test.py rate_limit	429 handling and fallback
python cli_test.py context_switch	Structured handoff vs raw history comparison
python cli_test.py provider_health	Error injection, degradation, recovery
python cli_test.py stress	20 concurrent requests, mixed tasks
python cli_test.py all	Run all scenarios

This is the zero-setup way to experience Switchboard. Someone finds this repo, runs python cli_test.py dry_run, sees the routing decisions in a pretty table — that's the "oh this is real" moment.

---

Contributing

Quick Start

git clone https://github.com/yourname/switchboard-mcp.git
cd switchboard-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

Adding a New Provider

1. Create providers/your_provider.py extending providers/base.py
2. Implement chat_complete() and health_check()
3. Register in config/models.yaml with the correct provider name
4. Add tests to tests/test_integration.py

Adding a New Model

Just edit config/models.yaml. No code changes needed:

- id: provider/model-name
  provider: openrouter     # or 'anthropic'
  cost_per_1k_tokens: 0.001
  context_window: 128000
  strengths: [code_generation, debugging]
  speed: fast
  tier: paid

Improving the Classifier

The classifier uses hybrid semantic + keyword scoring. To improve it:

1. Add keywords to CATEGORY_KEYWORDS in router/classifier.py
2. The semantic embeddings will automatically adapt to new text
3. Run pytest tests/test_router.py::TestClassifierStability to verify

PR Checklist

• All tests pass (pytest tests/ -v)
• New models added to config/models.yaml
• CHANGELOG.md updated
• No TODOs or stubs left in new code

See CONTRIBUTING.md for full details.

---

Roadmap

Version	Feature
v0.1.0	Initial release — hybrid router, 14 models, context handoff, health tracking
v0.2.0	Web dashboard for routing analytics and cost tracking
v0.3.0	Fine-tuned classifier trained on real routing data
v0.4.0	Cost analytics — per-session, per-project cost tracking and budgets
v0.5.0	Community model marketplace — share routing rules and model configs

---

What Makes This Different

Feature	Switchboard	LiteLLM / OpenRouter Router
MCP-native	✅ Zero-code-change for Claude Code, Cursor	❌ Requires SDK integration
Semantic context	✅ Structured handoff, not raw history	❌ Raw message forwarding only
Task-aware routing	✅ Understands debug vs review vs gen	❌ Cost/availability only
Feedback loop	✅ report_outcome tool	❌ None
Free-tier fallback	✅ Always 2+ free models	⚠️ Depends on plan
License	✅ MIT, for individual devs	⚠️ Hosted service / Enterprise

---

License

MIT — built for individual developers, not enterprise.

Made with ☕ at 2am because the rate limit wall needed to go.