DynamicMCPProxy

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.

1. Auto-Generation: Use proxy_activate_from_spec(name, url) to generate a server config in ./configs/ and mount it instantly.
2. 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",
  "receipts_enabled": true,
  "otel_enabled": false,
  "otel_service_name": "dynamic-mcp-proxy",
  "otel_exporter_otlp_endpoint": null,
  "otel_capture_content": false
}

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
• receipts_enabled — write JSONL receipts to audit_log_path with run_id, span_id, caller, status, latency, server/tool names, and privacy-safe argument summaries
• otel_enabled — optionally mirror receipt events into OpenTelemetry when opentelemetry-* packages are installed; JSONL receipts continue to work without those optional packages
• otel_capture_content — defaults to false; do not capture raw prompts, customer content, API keys, or tool payloads in traces by default

Receipts and Traceability

DynamicMCPProxy is the right place to collect agent receipts because every server activation and child MCP tool call passes through it. Receipts are enabled by default as local JSONL in audit.log and are designed for security-first debugging:

• Every record includes a run_id and span_id; related operations can pass a parent span where available.
• HMAC/JWT callers are identified by auth type, not by secret value. For example, sidecar HMAC calls record service:hmac.
• Tool arguments are summarized as keys, types, lengths, and SHA-256 fingerprints. Raw strings, nested payloads, passwords, tokens, cookies, and API keys are not logged.
• OpenTelemetry export is optional and dependency-optional. If enabled without the OTel packages installed, the proxy logs one warning to stderr and continues with JSONL receipts.

Example JSONL record shape:

{
  "ts": "2026-07-04T12:00:00+00:00",
  "event_type": "mcp.tool.call",
  "run_id": "run_...",
  "span_id": "...",
  "tool": "github_search",
  "caller": "service:hmac",
  "outcome": "ok",
  "latency_ms": 42.1,
  "server": "github",
  "argument_keys": ["query"],
  "redacted_args": {
    "query": {"type": "str", "length": 12, "sha256": "..."}
  }
}

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 / receipts — every tool call logged to audit.log (JSON lines) with privacy-safe argument fingerprints, not raw secrets or payloads
• 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:

1. 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.
2. 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.
3. 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.
4. 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

1. Client-agnostic — the proxy handles lazy loading transparently for any MCP client (Claude Code, Windsurf, Antigravity, opencode, Claude Desktop…), not just one IDE.
2. 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.
3. No fork required — add servers to catalogue.json or user.catalogue.json; the matcher and budget enforcement are automatic.

Inspiration

• FastMCP dynamic proxy pattern
• mcp-scan guardrail design
• Anti-Gravity Agents Prompt Protocol