Why

Web/app AIs can only connect to remote MCP servers, and most of them give you
just one custom connector slot. Meanwhile half the useful MCP servers are
local (npx/uvx stdio processes) that only Claude Desktop / a CLI can reach.

MCP Switch sits in the middle:

   local stdio MCP  ─┐
                     ┼──►  MCP Switch  ──►  one OAuth URL  ──►  claude.ai / ChatGPT / …
   yet another MCP  ─┘     (your VPS)

• Aggregate any number of MCP servers — remote (URL) or local (stdio, hosted on
  your box) — into one endpoint.
• Connect once. Your AI sees a single connector; behind it are all your tools.
• Manage from a console — add servers, group tools, scope which agent sees what,
  watch an audit log.
• Pure relay. MCP Switch ships no tools of its own; it forwards tools, schemas,
  results and even MCP-Apps UI widgets transparently.

Architecture

A single service (:4577) + a console SPA it serves:

No separate backend, no inter-service HTTP — the gateway talks to upstream
servers directly and aggregates them.

Quick start (Docker)

git clone https://github.com/asashiki/mcp-switch.git
cd mcp-switch
cp .env.example .env
# edit .env → set MCP_PUBLIC_URL to enable OAuth + the console (leave empty for local)

docker compose -f infra/docker/compose.yaml --env-file .env up -d --build

Then:

• Health: curl http://127.0.0.1:4577/health
• Console: open http://127.0.0.1:4577/console (set a password first — see below)

Behind a reverse proxy? Set MCP_PUBLIC_URL and MCP_GATEWAY_BIND_HOST=0.0.0.0 in .env.

Set the console password

docker compose -f infra/docker/compose.yaml exec mcp-switch \
  node dist/cli/console-admin.js set admin "your-password"

Quick start (local dev)

pnpm install
cp .env.example .env          # leave MCP_PUBLIC_URL empty for an anonymous local /mcp
pnpm dev                      # gateway :4577 + console :5173

Without MCP_PUBLIC_URL, the gateway serves an anonymous /mcp — handy for trying
it out locally before wiring up OAuth.

Connect an AI

In claude.ai → Settings → Connectors → Add custom connector, point it at:

https://<your MCP_PUBLIC_URL>/mcp

Complete the OAuth login (pick an agent identity in the consent screen). Your
aggregated tools now show up in the client.

Add upstream MCP servers

Open the console → Connect. Two ways:

Remote (HTTP). Paste the server URL; add headers (e.g. an API key) or OAuth if it
needs auth. Example — Context7:

{ "mcpServers": { "context7": {
  "serverUrl": "https://mcp.context7.com/mcp",
  "headers": { "CONTEXT7_API_KEY": "..." }
}}}

Local (stdio). MCP Switch spawns the process on your server and exposes it
remotely. Example — a Steam MCP via npx:

{ "mcpServers": { "steam": {
  "command": "npx",
  "args": ["-y", "steam-mcp-server"],
  "env": { "STEAM_API_KEY": "..." }
}}}

Paste either JSON straight into the console's import box — it auto-detects the
transport and fills the form. The container ships Node/npx; for uvx/Python
servers, add those runtimes to the image.

Configuration

All via .env (see .env.example):

Docs

• 📖 使用手册 — step-by-step walkthrough of the console.

Development

pnpm typecheck      # all packages
pnpm test           # gateway test suite (incl. an upstream→gateway e2e)
pnpm build          # build everything

Monorepo: apps/{mcp-gateway,console-web}, packages/{schemas,config}.

License

MIT