# mcp-switch

> JIT Namespace Loader for AI Agent Tools

mcp-switch is an MCP server that sits in front of your other MCP servers and CLI tools. Instead of loading 50 tool schemas into the agent's context window at startup, agents see 3 meta-tools: list_namespaces, load_namespace, and unload_namespace. Load only what you need, when you need it.

## Setup

Point any MCP client at mcp-switch using uvx (zero install):

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

This works with Claude Code, Cursor, Codex, Hermes, OpenClaw, Windsurf, Cline, and any MCP-compatible client.

For Claude Code specifically:
```bash
claude mcp add router -- uvx mcp-switch serve --config ~/.config/mcp-switch/config.yaml
```

## Configuration

Create ~/.config/mcp-switch/config.yaml:

```yaml
namespaces:
  # Proxy to a real MCP server (lazy startup)
  postgres:
    type: mcp
    command: "uvx mcp-server-postgres"
    args: ["--connection-string", "postgresql://localhost/mydb"]
    description: "Query and manage PostgreSQL databases"

  github:
    type: mcp
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    description: "Manage GitHub repos, issues, PRs"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

  # Wrap CLI commands as tools (no server needed)
  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"
```

## Tools

mcp-switch exposes 3 meta-tools:

- list_namespaces() - List all available namespaces with their descriptions and loaded status
- load_namespace(namespace) - Start the backend and add its tools to the agent's context
- unload_namespace(namespace) - Remove tools and optionally stop the backend

When load_namespace is called, backend tools are prefixed with the namespace (e.g., postgres__query, github__create_issue) and a tools/list_changed notification is sent so the client picks up the new tools.

## Namespace Types

- mcp: Proxies to a real MCP server via stdio. The server process is started lazily on first load.
- cli: Wraps shell commands as MCP tools. Parameters use {name} template substitution.

## Links

- Repository: https://github.com/Zer0Wav3s/mcp-switch
- License: MIT
