mcp-switch 0.4.1

Context-saving MCP switchboard for AI agents - lazy-load tools, resources, and prompts only when needed

🔀 mcp-switch

Give your AI agent only the MCP capabilities it needs, right when it needs them.

---

→ For agents: read llms.txt

→ For humans: send your agent this prompt:

Install mcp-switch (pip install mcp-switch) and use it as an MCP switchboard so only the needed namespaces are loaded at a time. Read https://raw.githubusercontent.com/Zer0Wav3s/mcp-switch/main/llms.txt for setup and usage.

What It Does

When you connect a pile of MCP servers to an agent, every tool usually gets dumped into context up front. That is dumb. More tools means more noise, slower tool selection, and worse calls.

mcp-switch fixes that by exposing 5 meta-tools first:

• list_namespaces
• load_namespace
• unload_namespace
• load_group
• unload_group

The agent starts focused, loads what it needs, then unloads it when done.

flowchart LR
    subgraph before["Without mcp-switch"]
        A1["🤖 Agent"] --> T1["46 tools loaded\n(database, GitHub, Slack,\nDocker, K8s...)"]
        T1 --> R1["❌ Slower, noisier,\nworse tool picks"]
    end

    subgraph after["With mcp-switch"]
        A2["🤖 Agent"] --> T2["5 meta-tools\n(list, load, unload,\nload_group, unload_group)"]
        T2 -->|"load_namespace('postgres')"| T3["+ only the database tools"]
        T3 --> R2["✅ Focused, fast,\nright tool at the right time"]
        T3 -->|"unload_namespace('postgres')"| T2
    end

    style before fill:#1a1a2e,stroke:#e74c3c,color:#fff
    style after fill:#1a1a2e,stroke:#2ecc71,color:#fff

How It Works

1. Define namespaces for MCP servers, hosted HTTP MCP endpoints, or CLI tools
2. Start mcp-switch as one MCP server in your client
3. Let the agent discover namespaces with list_namespaces
4. Load only what is needed with load_namespace or load_group
5. Unload when done to keep context clean

It supports:

• mcp backends - local stdio MCP servers
• http backends - remote MCP servers over StreamableHTTP with SSE fallback
• cli backends - shell commands wrapped as MCP tools
• groups
• idle_ttl, pinned, and max_loaded_namespaces
• tools, resources, resource templates, and prompts

Install

pip install mcp-switch

Or use uvx without installing globally:

uvx mcp-switch --help

Quick Start

1. Create a config

Fastest path:

uvx mcp-switch setup

Or import an existing MCP config:

uvx mcp-switch init
uvx mcp-switch init --from ~/.config/claude/claude_desktop_config.json

Or write one manually at ~/.config/mcp-switch/config.yaml:

max_loaded_namespaces: 3

namespaces:
  postgres:
    type: mcp
    command: "uvx mcp-server-postgres"
    args: ["--connection-string", "postgresql://localhost/mydb"]
    description: "Query and manage PostgreSQL databases"
    idle_ttl: 300

  supabase:
    type: http
    url: "https://mcp.supabase.com/mcp"
    headers:
      Authorization: "Bearer ${SUPABASE_TOKEN}"
    description: "Supabase database tools"

  git:
    type: cli
    description: "Git version control"
    tools:
      git_status:
        command: "git status --porcelain"
        description: "Show working tree status"
      git_log:
        command: "git log --oneline -20"
        description: "Show recent commits"

groups:
  dev:
    - git
    - postgres

2. Verify it works

uvx mcp-switch validate
uvx mcp-switch doctor
uvx mcp-switch test --json-output

3. Add it to your MCP client

General pattern:

{
  "mcpServers": {
    "mcp-switch": {
      "command": "uvx",
      "args": ["mcp-switch", "serve", "--config", "~/.config/mcp-switch/config.yaml"]
    }
  }
}

Examples:

Claude Code

claude mcp add mcp-switch -- uvx mcp-switch serve --config ~/.config/mcp-switch/config.yaml

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-switch": {
      "command": "uvx",
      "args": ["mcp-switch", "serve", "--config", "~/.config/mcp-switch/config.yaml"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "mcp-switch": {
      "command": "uvx",
      "args": ["mcp-switch", "serve", "--config", "~/.config/mcp-switch/config.yaml"]
    }
  }
}

Hermes

mcp_servers:
  mcp-switch:
    command: uvx
    args: ["mcp-switch", "serve", "--config", "~/.config/mcp-switch/config.yaml"]

Or generate it:

uvx mcp-switch export hermes

Features

Namespace groups

Load related namespaces together:

groups:
  dev:
    - git
    - postgres
    - docker

Auto-unload with idle_ttl

Unload inactive namespaces automatically to keep context lean.

Pinned namespaces

Mark important namespaces as pinned: true so LRU eviction never removes them.

Max loaded namespace cap

Set max_loaded_namespaces to enforce a ceiling. If the cap is reached, mcp-switch evicts the least recently used unpinned namespace.

Full MCP surface

Tools are the main event, but resources, resource templates, and prompts are also proxied.

CLI

mcp-switch setup                  # interactive config wizard
mcp-switch init                   # import existing MCP configs
mcp-switch serve                  # start the MCP server
mcp-switch validate               # validate config
mcp-switch doctor                 # check env, commands, config health
mcp-switch test                   # connect to backends and list tools
mcp-switch status                 # config and policy summary
mcp-switch list                   # list configured namespaces
mcp-switch export hermes          # generate client-specific config

Troubleshooting

${VAR} values are not resolving

Use standard shell-style placeholders like ${SUPABASE_TOKEN}. mcp-switch expands them in both env and HTTP headers values.

doctor says an env var is missing

That means the placeholder resolved to an empty string in your current environment. Set it first, then rerun mcp-switch doctor.

Agent is not seeing new tools after loading

Some clients cache tool lists aggressively. mcp-switch sends tools/list_changed, but if your client ignores it, reconnect the MCP server.

Why does status not show what is live right now?

Because status is a config and policy summary, not a runtime inspector.

Links

• Repository: https://github.com/Zer0Wav3s/mcp-switch
• PyPI: https://pypi.org/project/mcp-switch/
• License: MIT © 2026 ZeroWaves