mcp-switchboard

<div align="center"> <img src="docs/assets/switchboard-banner.svg" alt="MCP Switchboard — one governed MCP endpoint for every tool, shared by Claude and ChatGPT, running local-first on your machine" width="880" /> <h1>🔌&nbsp;MCP Switchboard</h1> <p> <b>One connector. Every tool. Both Claude <i>and</i> ChatGPT</b> — driving the same apps through one governed control plane on your machine.<br/> Local-first · bring your own keys · run fully offline with a local LLM · <b>nothing leaves your machine</b>. </p>

<p> <a href="#quickstart"><b>Quickstart</b></a> · <a href="#why-its-different">Why it's different</a> · <a href="#the-big-idea">The big idea</a> · <a href="#cli">CLI</a> · <a href="#everything-is-verified-by-a-deterministic-oracle">Verified</a> · <a href="#docs">Docs</a> </p> </div>

---

The big idea

You have two of the best agents in the world — Claude and ChatGPT — and you'd like them to actually do things: read your GitHub, triage your Gmail, update Notion, ping Slack, hit your internal API. Today that means wiring every client to every app by hand (N×M pain), and the "easy" hosted shortcut parks your OAuth tokens on someone else's server.

MCP Switchboard collapses N×M into N×1. You run one local process that re-exposes all your MCP servers behind one governed endpoint. You add that endpoint once as a connector in Claude, and once in ChatGPT — and now both assistants reach the same tools, through the same encrypted vault, the same on/off + read/write/full policy, the same approval gates, and the same audit log. One control plane. Your machine. No "us" in the middle.

Think of it as your own private "Connectors" page — the kind ChatGPT and Claude each ship as a walled garden — except it lives on your box, mounts the whole MCP ecosystem instead of a curated shortlist, and serves every assistant at once. Browse a catalog of thousands of toolkits in the dashboard, flip one on, and switchboard install claude-code wires it into your client in a single command. No tokens handed to a vendor, no per-call meter, no treadmill.

     Claude Desktop ─┐                            ┌─ Gmail        (read)
     Claude Code  ───┤       ┌────────────┐       ├─ GitHub       (write · delete blocked)
     claude.ai web ──┼─ MCP ▶│ SWITCHBOARD │▶──────┼─ Notion       (read)
     ChatGPT      ───┤       │ vault·policy│       ├─ Slack        (OFF)
     Cursor/agents ──┘       │ ·audit·gates│       ├─ your REST API (app2mcp)
                             └────────────┘       └─ a local LLM   (offline council)

"So Claude and ChatGPT share my email?" — almost; here's the precise mental model

You're right that MCP Switchboard is the single connector both assistants point at to reach every app. Two corrections worth making:

• It's a shared control plane, not a shared session. Claude and ChatGPT don't see each other's chats or share conversation state. What they share is the layer underneath: one set of BYO credentials, one policy, one audit trail. Both can act on your Gmail — each governed identically, every call logged in one place — but neither inherits the other's context.
• Local clients connect directly; cloud clients need a door. Anything running on your machine (Claude Desktop, Claude Code, Cursor, your own agents) reaches 127.0.0.1:8088 directly with an API key — zero setup. Anything running in a vendor's cloud — claude.ai web and ChatGPT's custom connectors (Developer Mode, on Pro/Team/Enterprise/Edu) — cannot reach your laptop's localhost. For those, run switchboard expose to get a public HTTPS URL and turn on the built-in OAuth 2.1 + PKCE server, then paste that URL as the connector and authorize once. Same governed endpoint, reachable from the cloud, still zero token custody. See Connecting cloud clients.

No cloud account? Run it fully offline.

Adoption shouldn't require an API bill. Point MCP Switchboard's council at a local LLM — Ollama, LM Studio, llama.cpp, or vLLM — and you get a second-opinion / debate model with zero cloud, zero keys, zero data leaving the box. You don't even have to find the URL: switchboard local-llm auto-detects a running OpenAI-compatible server on the usual ports, and switchboard local-llm wire writes the provider block for you. Download a model, run two commands, and the whole stack (vault, policy, audit, council) runs on your hardware. See Run it fully offline with a local LLM.

Why it's different

| | MCP Switchboard | Hosted tool routers | |---|---|---| | One connector, every assistant | Add it once; Claude and ChatGPT share the same governed tools | Per-vendor, per-app setup | | Where your tokens live | A local AES-256 vault on your machine | Their cloud | | Integrations | Mounts existing MCP servers — no treadmill | Hand-built, must be maintained | | One-command setup | switchboard install claude-code wires it into 5 clients | Copy-paste JSON per client | | Browse & connect | A local catalog of thousands of toolkits (MCP Registry + APIs.guru) | A curated vendor shortlist | | Governance | Per-tool read/write/full + approval gates + audit log | Usually all-or-nothing | | Profiles | Named views — a locked-down "demo" vs a full "dev" surface, one switch | None | | Rate limits + spend budgets | Per-minute/hour/day call and cost ceilings, fail-closed | Pay the overage | | Resilience | Per-server circuit breaker trips a flapping upstream, fast-fails | Hangs propagate | | Works offline | Council runs against an auto-detected local LLM — no account required | Cloud-only | | Context blow-up | search mode → 2 meta-tools no matter how many servers | Dump every tool into context | | Cost | Free, Apache-2.0, self-hosted, no per-call meter | Metered SaaS |

The catalog is not the moat — hosted players already have bigger ones. The defensible combination is local credentials + a governance layer + a usable dashboard, built as an aggregator that rides the existing MCP ecosystem instead of re-implementing it — then pushed past parity with the three things a metered cloud can't sell you: profiles, spend budgets, and a circuit breaker, all running on your own hardware.

Quickstart

Install from GitHub release tarball

One-time prerequisite: install Node 18.18+.

npm install -g https://github.com/Mas-AI-Official/mcp-switchboard/releases/download/v0.1.0/mcp-switchboard-0.1.0.tgz   # installs the `switchboard` command globally
switchboard init                 # scaffold a config + the ~/.switchboard home directory
switchboard serve                # stdio for local clients + HTTP endpoint & dashboard

The npm package name is pending publication. Until npm auth is completed, use the release tarball above.

Uninstall is plain npm:

npm uninstall -g mcp-switchboard

# Optional: delete local Switchboard state too.
# This removes your local vault, API keys, auth-server state, and audit/config files.
rm -rf ~/.switchboard

Windows PowerShell equivalent:

npm uninstall -g mcp-switchboard
Remove-Item -Recurse -Force "$env:USERPROFILE\.switchboard"

Open the dashboard at http://127.0.0.1:8088, then point an agent at the MCP endpoint. Wire a client in one command with switchboard install <client> (see below).

Fastest start — one click (no terminal)

One-time prerequisite: install Node 18.18+.

1. Get the code — git clone https://github.com/Mas-AI-Official/mcp-switchboard.git, or Code ▸ Download ZIP on GitHub and unzip it.
2. Windows: double-click start-switchboard.bat. macOS / Linux: run ./start-switchboard.sh (chmod +x start-switchboard.sh once).
3. That's it. The first run installs dependencies, builds, and writes a starter config for you; then the gateway starts and the dashboard opens in your browser automatically.

To stop it: press Ctrl+C in the launcher window — or, if you closed the window and the port is still busy, double-click stop-switchboard.bat (./stop-switchboard.sh isn't needed on Unix; Ctrl+C is enough).

The launcher runs MCP Switchboard in HTTP + dashboard mode on http://127.0.0.1:8088. To wire a stdio client (claude mcp add, Cursor) or change the transport, edit switchboard.config.yaml or use the from-source commands below.

From source (manual)

Requires Node ≥ 18.18. Prefer this if you want to hack on MCP Switchboard or pin a specific commit.

git clone https://github.com/Mas-AI-Official/mcp-switchboard.git
cd switchboard
npm install
npm run build

# scaffold a config + the ~/.switchboard home directory
node dist/cli.js init

# mount everything and print the governed tool list (no credentials needed —
# the bundled @modelcontextprotocol/server-everything is a real test server)
node dist/cli.js list

# run it: stdio for local clients + an HTTP endpoint & dashboard
node dist/cli.js serve

Open the dashboard at http://127.0.0.1:8088, then point an agent at the MCP endpoint.

Wire it into your client — one command

switchboard install <client> writes the right config block, in the right file, for the client you name — Claude Desktop, Claude Code, Cursor, VS Code, or Codex — so you never hand-edit a JSON config:

node dist/cli.js install claude-code        # project-local config in the current dir
node dist/cli.js install claude-desktop --global   # the client's user/global config
node dist/cli.js install cursor --print     # preview the exact block without writing it

It is non-destructive — it merges into the client's existing servers, never clobbers them — and --print shows you exactly what it would write first. Prefer to wire it by hand? The endpoints are:

# Claude Code / Claude Desktop, stdio transport:
claude mcp add switchboard -- node /absolute/path/to/switchboard/dist/cli.js serve

# or the Streamable HTTP endpoint, for any HTTP MCP client:
#   http://127.0.0.1:8088/mcp

Storing a secret (BYO keys)

Secrets never appear in your config — the config holds only ${vault:name} references.

# pipe the value in so it stays out of your shell history
printf '%s' 'ghp_xxx' | node dist/cli.js vault set github_pat
node dist/cli.js vault list      # names only, never values

# switchboard.config.yaml
servers:
  - id: github
    source: npx
    package: "@modelcontextprotocol/server-github"
    enabled: true
    policy: write
    credentials:
      GITHUB_TOKEN: ${vault:github_pat}   # resolved locally at mount time
    tools:
      delete_repo: { enabled: false }     # hard-block the destructive one

Connecting an OAuth provider (Phase 3)

For the five managed providers you don't paste a token — you authorize once and MCP Switchboard seals the result in the vault. Store the provider's client credentials, then run the loopback flow:

# one-time: store the OAuth app's client id/secret (names are a fixed convention)
printf '%s' '<cli