mcp-proxy

An aggregating MCP proxy that reduces context window usage by ~95% while providing zero-latency tool execution.

How It Works

Instead of exposing all tools directly to Claude (consuming ~15,000+ tokens), mcp-proxy exposes just 2 meta-tools:

1. get_tools_in_category - Navigate a hierarchical tree of available tools
2. execute_tool - Execute any tool by its path

This progressive disclosure pattern reduces context to ~800 tokens while maintaining full access to all tools.

Features

Feature	Benefit
95% context reduction	~800 tokens instead of ~15,000
Background preloading	Zero cold-start latency
Multi-transport	stdio, SSE, HTTP Streamable
Graceful degradation	Failed servers disabled, don't block
Secrets integration	Optional OpenBao/Vault support
Source-based installation	MCP servers installed from git/local sources
Portable config	Variable expansion for machine-independent configs

Quick Start

# 1. Clone
git clone https://github.com/IAMSamuelRodda/mcp-proxy.git
cd mcp-proxy

# 2. Create your config
cp config/config.template.json config/config.local.json

# 3. Edit config.local.json:
#    - Remove example-* entries
#    - Add your MCP servers with source URLs
#    - Keep ${VARIABLES} as-is (expanded automatically)

# 4. Bootstrap (validates config, installs servers, updates ~/.claude.json)
./scripts/bootstrap.sh

# 5. Restart Claude Code

Minimal Config Example

{
  "mcpProxy": {
    "hierarchyPath": "${MCP_PROXY_DIR}/hierarchy",
    "options": { "lazyLoad": true, "preloadAll": true }
  },
  "mcpServers": {
    "my-server": {
      "source": { "type": "git", "url": "https://github.com/you/my-mcp.git" },
      "transportType": "stdio",
      "command": "${MCP_SERVERS_DIR}/my-server/.venv/bin/python",
      "args": ["${MCP_SERVERS_DIR}/my-server/server.py"],
      "envFile": "${MCP_SERVERS_DIR}/my-server/.env",
      "env": {},
      "options": { "lazyLoad": true }
    }
  }
}

Key points:

• Use ${MCP_SERVERS_DIR} for server paths (expands to ~/.claude/mcp-servers)
• Use ${MCP_PROXY_DIR} for proxy paths (expands to ~/.claude/mcp-proxy)
• Add envFile for .env secrets OR use env: {} for inline variables
• Every server needs a source for bootstrap to install it

Bootstrap Workflow

The bootstrap script orchestrates full workstation setup:

./scripts/bootstrap.sh [FLAGS]

Flag	Behavior
(none)	Default: MCP servers → mcp-proxy
--secure	Include secrets infrastructure (bitwarden-guard, openbao-agents)
--refresh	Config + hierarchy only (fast, skips source updates)
--force	Clean reinstall all MCP servers from source

What it does:

1. Validates config - Checks for missing/placeholder values
2. Installs MCP servers - Clones from git, creates venvs
3. Builds mcp-proxy - Compiles Go binary + structure generator
4. Deploys - Copies to ~/.claude/mcp-proxy/, expands variables
5. Updates ~/.claude.json - Adds mcp-proxy entry automatically
6. (--secure only) Installs bitwarden-guard + openbao-agents

Configuration

Portable Config with Variables

Config files use variables that are expanded at deploy time:

{
  "mcpProxy": {
    "hierarchyPath": "${MCP_PROXY_DIR}/hierarchy"
  },
  "mcpServers": {
    "my-server": {
      "source": {
        "type": "git",
        "url": "https://github.com/user/mcp-server.git"
      },
      "command": "${MCP_SERVERS_DIR}/my-server/.venv/bin/python",
      "args": ["${MCP_SERVERS_DIR}/my-server/server.py"]
    }
  }
}

Available variables:

Variable	Default
${MCP_SERVERS_DIR}	~/.claude/mcp-servers
${MCP_PROXY_DIR}	~/.claude/mcp-proxy
${HOME}	User home directory

Source Types

Each MCP server can specify a source for installation:

Git source (recommended):

"source": {
  "type": "git",
  "url": "https://github.com/user/mcp-server.git"
}

Local source (for development):

"source": {
  "type": "local",
  "path": "~/repos/my-mcp-server"
}

Remote HTTP (no installation needed):

"transportType": "streamable-http",
"url": "https://example.com/mcp"

Update Behavior

Source Type	Update Mechanism
Git	git pull on each bootstrap run
Local	Clean replace (rm + cp) preserving .venv
Remote	No installation, connects directly

Venv rebuilds only occur when pyproject.toml or requirements.txt changes (hash-based detection).

Setup Options

Mode	Secrets Storage	Best For
Simple	.env files per server	Local dev, single machine
Secure	OpenBao + Bitwarden	Production, multi-machine, audit trails

Simple mode: Configure MCP servers with environment variables. See config.template.json.

Secure mode: Full secrets management with OpenBao, Bitwarden integration. See docs/SECURE_SETUP.md.

Claude Code Integration

Add to ~/.claude.json:

{
  "mcpServers": {
    "mcp-proxy": {
      "type": "stdio",
      "command": "~/.claude/mcp-proxy/mcp-proxy",
      "args": ["--config", "~/.claude/mcp-proxy/config.json"]
    }
  }
}

⚠️ CRITICAL: Your ~/.claude.json should contain ONLY the mcp-proxy entry above.

Remove all other MCP server entries (cloudflare, joplin, etc.) - the proxy handles them.

Having both direct servers AND mcp-proxy causes duplicate connections and wasted context.

The install script will detect this and prompt you to clean up automatically.

Architecture

┌─────────────────────────────────────────────────────┐
│                   Claude Code                        │
│                        │                             │
│                        ▼                             │
│         ┌──────────────────────────────┐            │
│         │         mcp-proxy            │            │
│         │                              │            │
│         │  2 meta-tools (~800 tokens)  │            │
│         │  • get_tools_in_category()   │            │
│         │  • execute_tool()            │            │
│         │                              │            │
│         │  Background: preload all     │            │
│         └──────────────────────────────┘            │
│                        │                             │
│     ┌──────────────────┼──────────────────┐         │
│     ▼                  ▼                  ▼         │
│ [Server 1]        [Server 2]        [Server 3]      │
│   warm              warm              warm          │
└─────────────────────────────────────────────────────┘

Project Structure

mcp-proxy/
├── cmd/mcp-proxy/         # Main entry point
├── internal/
│   ├── client/            # MCP client connections
│   ├── config/            # Configuration parsing
│   ├── hierarchy/         # Tool schema management
│   ├── secrets/           # Secrets provider interface
│   └── server/            # Proxy server logic
├── structure_generator/   # Hierarchy generation tool
├── config/                # Configuration templates
│   ├── config.template.json   # Portable template with variables
│   └── config.local.json      # Your local config (gitignored)
├── scripts/
│   ├── bootstrap.sh       # Full setup (MCP servers + proxy) - recommended
│   ├── install.sh         # Binary-only (if servers already installed)
│   └── install-go.sh      # Install Go if missing
└── docs/
    └── SECURE_SETUP.md    # OpenBao + Bitwarden guide

Development

# Build
make build

# Test
go test ./...

# Deploy binary only (keeps existing config)
make deploy

# Full install (binary + config from config.local.json)
make install

# Regenerate hierarchy only
make generate-hierarchy

Acknowledgments

This project was inspired by voicetreelab/lazy-mcp, which introduced the elegant 2-meta-tool pattern for progressive tool disclosure. mcp-proxy extends this foundation with background preloading, multi-transport support, secrets integration, and production resilience features.

License

MIT License