Dynamic MCP Proxy

A smart MCP proxy server that lazily loads relevant MCP tool servers based on your project context, keeping AI tool counts within recommended limits (≤ 50 tools for Google Antigravity). Designed specifically for high-autonomy environments where agents need to evolve their own toolsets.

Part of the Anti-Gravity Agents Prompt Protocol ecosystem.

*This project is a working, client-agnostic solution to anthropics/claude-code#7336 — Feature Request: Lazy Loading for MCP Servers and Tools.* See Related Work below.

How It Works

IDE connects → proxy exposes proxy_* tools + MCP Resources + Prompts
AI calls proxy_handshake({ tech_stack, task_description })
  → Matcher scores catalogue entries
  → Top-5 servers activated (lazily mounted as stdio subprocesses or SSE)
  → tools/list now includes those servers' tools
  → Budget cap (50 tools) enforced via LRU eviction

Quick Start

Prerequisites

Catalogue servers run via npx (Node.js) and uvx (uv). These must be on the PATH your IDE uses when spawning the proxy. Add them explicitly in the MCP config env block (see below). Find your paths with type npx and type uvx.

Install

Install with the hardened installer (clone-or-install-in-place):

curl -fsSL https://raw.githubusercontent.com/SPhillips1337/DynamicMCPProxy/main/install.sh -o install.sh
chmod +x install.sh
./install.sh --dir "$HOME/DynamicMCPProxy"

If you already cloned the repository, run the installer from the project root:

./install.sh

The installer validates that an existing target directory is this repository before updating it, checks for required tools (git and uv), runs uv sync, and creates proxy_config.json from proxy_config.json.example when needed. For inspect-first installs, download and review the script before executing it; avoid piping remote scripts directly into a shell unless you trust the source.

Manual install remains:

uv sync

Configure

Copy the example config:

cp proxy_config.json.example proxy_config.json

Set up your environment and private catalogue:

cp .env.example .env          # fill in your API keys
# user.catalogue.json is auto-created or copy from your IDE's mcp_config.json

Add to your IDE (Antigravity / opencode / Claude Desktop)

{
  "mcpServers": {
    "dynamic-proxy": {
      "command": "uv",
      "args": [
        "run",
        "--quiet",
        "--project",
        "/path/to/dynamic-mcp-proxy-server",
        "python", "-m", "src.proxy_server"
      ],
      "env": {
        "PATH": "/home/user/.nvm/versions/node/v20.18.1/bin:/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Adjust PATH to match your system (type npx and type uvx show the right directories).

proxy_* Tools

| Tool | Description | |---|---| | proxy_handshake(tech_stack, task_description, ...) | Context handshake — activates relevant servers | | proxy_list_active_servers() | Currently mounted servers + tool counts | | proxy_list_available_servers(filter_tag?) | Browse catalogue | | proxy_activate_server(name, eager?) | Mount a server (deferred by default) | | proxy_activate_from_spec(name, url, type?, lean?) | Generate & mount server from OpenAPI/GraphQL (lean=True uses LAP for smaller specs) | | proxy_deactivate_server(name) | Free up tool budget | | proxy_add_custom_proxy(name, url, tags, runtime) | Add an ad-hoc server (SSE/HTTP only) | | proxy_list_tools(server_name?) | List exact names of all mounted tools | | proxy_inspect_registry() | Diagnostic: Full dump of current tool registry | | proxy_get_metrics() | Live memory/CPU/uptime metrics | | proxy_get_usage() | Server usage counts for self-evolving ranking | | proxy_reset_usage(server?) | Reset usage stats (for testing/re-baselining) |

MCP Resources

| URI | Description | |---|---| | mcp://proxy/info | Static metadata (version, capabilities) | | mcp://proxy/health | Live health (uptime, memory, active tools) | | mcp://proxy/servers | Full server inventory (active + available) |

MCP Discovery Surface

| MCP Method | What the AI Sees | |---|---| | tools/list | Minimal proxy_* management tools | | resources/list + resources/read | Live health, proxy info, server inventory | | prompts/list | suggest_tools_for_context guided workflow |

Catalogue

catalogue.json — 49 public MCP servers (GitHub, Docker, Postgres, Slack, Stripe, etc.).

user.catalogue.json — your private overlay (gitignored). Add personal servers here — local paths, private APIs, custom tools. Entries with the same name override the public catalogue.

[
  {
    "name": "my-server",
    "description": "My private MCP server",
    "command": "python /path/to/server.py",
    "tags": ["custom"],
    "tech_stack": ["any"],
    "runtime": "stdio",
    "env_vars": ["MY_API_KEY"],
    "pick": ["id", "status"],
    "token_budget": 500
  }
]

Response Steering

Optimize AI context usage by shaping server responses before they reach the LLM. Applied to any server (stdio, SSE, REST):

pick: Array of dot-notation paths to keep (all others dropped).
omit: Array of paths to remove.
template: Python-style format string (e.g., "{id}: {content}") to flatten complex JSON into readable text.
token_budget: Hard character cap (approx tokens * 4) to prevent context flooding.

REST Bridge Support (via 40mcp)

The proxy supports runtime: "rest", allowing it to act as a bridge for any OpenAPI or GraphQL API.

Auto-Generation: Use proxy_activate_from_spec(name, url) to generate a server config in ./configs/ and mount it instantly.
Manual Config: Add an entry with "runtime": "rest" and "config_path": "configs/mysvc.json". The proxy uses the 40mcp engine to map MCP tool calls to REST/GraphQL requests.

Environment Variables

.env (gitignored) is loaded automatically at startup. Copy .env.example to get started:

cp .env.example .env

Keys follow the env_vars field in each catalogue entry. Values in real environment variables always take precedence over the .env file.

Configuration

proxy_config.json (gitignored, auto-generated with safe defaults):

{
  "tool_budget": 50,
  "auth_enabled": false,
  "guardrails_enabled": true,
  "rate_limit_rpm": 120,
  "catalogue_path": "catalogue.json",
  "audit_log_path": "audit.log"
}

Key settings:

tool_budget — max tools exposed at once (default 50, matches Antigravity limit)
auth_enabled — JWT RS256 + HMAC API key auth for production use
guardrails_enabled — prompt-injection scanning + result size caps

Security

When auth_enabled = true:

JWT (RS256) — set jwt_public_key_path to your RSA public key PEM
HMAC API key — set hmac_api_key (passed via X-API-Key header)
Guardrails — 8 prompt-injection pattern checks on all tool descriptions
Audit log — every tool call logged to audit.log (JSON lines)
Rate limiting — configurable RPM per caller

Hot-Plug Plugins

Drop any executable MCP server script into ./plugins/. The proxy detects it via watchdog and registers it live — no restart needed.

Autonomous Tooling & Hot-Swap

The real power of this proxy lies in Runtime Mutation. Unlike static MCP configurations, this proxy allows an agent to "evolve" its toolbox as the task progresses:

Just-in-Time Activation: A2A (Agent-to-Agent) workflows that run for hours can activate sequential-thinking only when hitting a complex logic gate, then swap it for docker or terraform during the execution phase.
Autonomous Bootstrap: An agent can research a new tool, configure its environment via proxy_add_custom_proxy, and begin using it immediately without human intervention.
Self-Correction: If a tool is missing, an agent can literally write a new MCP server to ./plugins/ and the proxy will hot-plug it instantly.
Token Sustainability: By keeping the active toolset lean (via LRU eviction), long-running agents avoid context-window saturation and maintain peak focus on the task.

Update the Public Catalogue

uv run python scripts/sync_catalogue.py

Run Tests

uv run pytest tests/ -v

Optional HTTP Endpoint

Disabled by default. Enable with ENABLE_HTTP_SIDECAR=1:

curl -X POST http://localhost:8765/handshake \
  -H "Content-Type: application/json" \
  -d '{"tech_stack": ["python", "fastapi"], "task_description": "Building a REST API"}'

Long-Term Memory

This project uses the Anti-Gravity LTM protocol. The repo ships canonical memory in docs/memories/. Per-developer context lives in .antigravity/memories/ (gitignored):

patterns_and_lessons.md — solved problems, failure post-mortems
codebase_insights/ — module-level hidden knowledge
architectural_decisions/ — design tradeoffs and rationale

Bootstrap your local LTM by following BOOTSTRAP.md from the protocol repo. See AGENTS.md for the full agent protocol.

Repository Documentation

README.md — user overview and getting started
CONTEXT.md — concise operating manual (stack, rules, decisions, guidance)
AGENTS.md — agent behavior, workflow rules, and LTM protocol (HERMES equivalent)
docs/memories/ — living memory: patterns, insights, architectural decisions
research/ — external references, comparisons, and notes (not source of truth)

Related Work & Problem Context

anthropics/claude-code#7336 documented a real problem: loading all MCP servers at session startup can consume 54 % of the available context window (~108k of 200k tokens) before a single message is sent. Several approaches have been proposed or built:

| Project | Approach | Limitation | |---|---|---| | machjesusmoto/claude-lazy-loading | Offline registry generator — produces a lightweight token index from your MCP config | No runtime injection; explicitly lists "Automatic lazy loading at runtime" as needing Claude Code support | | block-town/mcp-gateway | Replaces all tools with 3–4 generic gw(service, tool, args) shim tools; dispatches at call time | Hard-coded, requires fork-and-edit per stack; the AI loses full tool type-safety and discovery | | This project | Smart proxy that activates only the servers relevant to the current project context via proxy_handshake(), enforces a tool budget via LRU eviction, and is fully dynamic at runtime | Works with any MCP client today — no IDE changes required |

Why the MCP layer is the right place to solve this

Client-agnostic — the proxy handles lazy loading transparently for any MCP client (Claude Code, Windsurf, Antigravity, opencode, Claude Desktop…), not just one IDE.
proxy_handshake() already delivers the "After" UX from the issue — the feature request's ideal example shows > Auto-loading: context7, magic [+3.5k tokens] after detecting keywords in user input. That is exactly what proxy_handshake({ tech_stack, task_description }) does today.
No fork required — add servers to catalogue.json or user.catalogue.json; the matcher and budget enforcement are automatic.

DynamicMCPProxy