Metadata-Version: 2.4
Name: mcp-switch
Version: 0.4.1
Summary: Context-saving MCP switchboard for AI agents - lazy-load tools, resources, and prompts only when needed
Project-URL: Homepage, https://github.com/Zer0Wav3s/mcp-switch
Project-URL: Repository, https://github.com/Zer0Wav3s/mcp-switch
Project-URL: Issues, https://github.com/Zer0Wav3s/mcp-switch/issues
Author: ZeroWaves
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,claude-code,codex,cursor,hermes,lazy-loading,mcp,model-context-protocol,namespace,proxy,tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.12.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🔀 mcp-switch

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

[![PyPI](https://img.shields.io/pypi/v/mcp-switch?style=for-the-badge&logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/mcp-switch/)
[![License](https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge)](LICENSE)

</div>

---

### → For agents: read [`llms.txt`](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.

```mermaid
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

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

Or use `uvx` without installing globally:

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

## Quick Start

### 1. Create a config

Fastest path:

```bash
uvx mcp-switch setup
```

Or import an existing MCP config:

```bash
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`:

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

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

### 3. Add it to your MCP client

General pattern:

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

Examples:

<details>
<summary><strong>Claude Code</strong></summary>

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

</details>

<details>
<summary><strong>Cursor</strong></summary>

Add to `.cursor/mcp.json`:

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

</details>

<details>
<summary><strong>VS Code</strong></summary>

Add to `.vscode/mcp.json`:

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

</details>

<details>
<summary><strong>Hermes</strong></summary>

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

Or generate it:

```bash
uvx mcp-switch export hermes
```

</details>

## Features

### Namespace groups
Load related namespaces together:

```yaml
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

```bash
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
