# mcp-switch

> Context-saving MCP switchboard for AI agents.

mcp-switch sits in front of your MCP servers and CLI tools so agents do not load everything up front. Instead of exposing every tool schema at startup, it exposes 5 meta-tools first:

- `list_namespaces`
- `load_namespace`
- `unload_namespace`
- `load_group`
- `unload_group`

## What 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`, `max_loaded_namespaces`
- tools, resources, resource templates, and prompts

## Install

```bash
pip install mcp-switch
```

Or run without installing globally:

```bash
uvx mcp-switch --help
```

## Quick setup

```bash
uvx mcp-switch setup
uvx mcp-switch validate
uvx mcp-switch doctor
uvx mcp-switch test --json-output
```

Default config path:

- `~/.config/mcp-switch/config.yaml`

General MCP client config:

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

## Example 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
```

## Core commands

- `mcp-switch setup`
- `mcp-switch init`
- `mcp-switch serve`
- `mcp-switch validate`
- `mcp-switch doctor`
- `mcp-switch test [namespace] --json-output`
- `mcp-switch status`
- `mcp-switch list`
- `mcp-switch export <client>`

## Notes for agents

- `status` is a config and policy summary, not a live runtime inspector.
- `${VAR}` placeholders resolve inside both `env` and HTTP `headers` strings.
- `doctor` reports missing env vars referenced by placeholders.
- `export hermes` returns YAML, not JSON.

## Repo

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