Skip to main content
Glama

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

Related MCP server: MCP Coordinator

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)

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

Available Tools

13 tools
proxy_activate_from_specA

Generate an MCP server from an OpenAPI/GraphQL spec and activate it.

Args: name: A unique name for this generated server spec_url: URL to the OpenAPI spec (JSON/YAML) or GraphQL endpoint spec_type: 'openapi' or 'graphql' eager: If True, mount the server immediately lean: If True, attempt to use LAP (https://lap.sh) to produce a dramatically leaner input spec before 40mcp generation (F-12 research slice). Falls back gracefully if LAP CLI not available.

Inputs: name (required), spec_url (required), lean, eager, +1 more. Returns: result

proxy_activate_serverA

Activate (mount) a server from the catalogue by name.

By default the server is registered as a deferred stub ({name}_load tool) and only fully spawned when first used. Pass eager=True to mount immediately.

Args: name: Server name as shown in proxy.list_available_servers() eager: If True, spawn the subprocess immediately instead of deferring.

Inputs: name (required), eager. Returns: result

proxy_add_custom_proxyA

Register a custom (non-catalogue) MCP server and optionally activate it. Only SSE and HTTP runtimes are accepted; stdio is restricted to prevent arbitrary command execution.

Args: name: A unique identifier for this server url: SSE URL (e.g. http://localhost:8100/sse) or HTTP URL tags: Tag list for future discovery matching runtime: "sse" or "http" (stdio is not permitted for custom proxies) activate_now: If True, mount the server immediately

Inputs: url (required), name (required), tags, runtime, +1 more. Returns: result

proxy_deactivate_serverA

Deactivate (unmount) a currently loaded or pending server to free up tool budget.

Args: name: Server name as shown in proxy.list_active_servers()

Inputs: name (required). Returns: result

proxy_get_metricsA

Return live process metrics for the proxy itself. Mirrors the mcp://proxy/health resource as a callable tool.

Inputs: no named parameters. Returns: result

proxy_get_usageB

Return current server usage counts for self-evolving ranking (F-13).

Inputs: no named parameters. Returns: result

proxy_handshakeA

Send your project context to the proxy. It will activate the most relevant MCP servers from the catalogue and return a summary of available tools.

Args: tech_stack: Languages and frameworks in use, e.g. ["python", "fastapi", "postgres"] task_description: Free-text description of what you are working on open_files: File paths currently open in the IDE (optional, helps infer stack) requirements: Package names from requirements.txt / package.json (optional)

Inputs: tech_stack (required), open_files, requirements, task_description. Returns: result

proxy_inspect_registryB

Diagnostic tool: Expose proxy state and server counts.

Inputs: no named parameters. Returns: result

proxy_list_active_serversA

List all currently mounted MCP servers and their estimated tool counts.

Inputs: no named parameters. Returns: result

proxy_list_available_serversA

List MCP servers in the catalogue that are not yet mounted.

Args: filter_tag: Optional tag filter, or free-text query (uses search_servers for discovery).

Inputs: filter_tag. Returns: result

proxy_list_toolsA

List all registered tools by inspecting the FastMCP instance. If server_name is provided, filters for tools from that child server.

Inputs: server_name. Returns: result

proxy_reset_usageA

Reset usage stats (all or for one server). Useful for testing or re-baselining.

Inputs: server. Returns: result

proxy_search_toolsA

Search the catalogue for relevant servers/tools using free-text query. Enables on-demand discovery (lazy loading pattern) so the AI can find specific capabilities without the full catalogue bloating context.

Returns ranked list of matching servers (name, desc, score, tags). Use proxy_activate_server on results, or let handshake do it.

Inspired by MCP tool search / lazy discovery best practices (Anthropic, Stacklok, etc.).

Inputs: query (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: handshake, listing servers, searching, activation/deactivation, spec generation, metrics, usage tracking, etc. No two tools appear to overlap in functionality.

    Naming Consistency5/5

    All tools follow the 'proxy_verb_noun' pattern with consistent snake_case. Verbs like 'list', 'activate', 'get', 'reset' are used uniformly, making the naming predictable.

    Tool Count5/5

    13 tools is well-scoped for a proxy management server, covering setup, discovery, activation, inspection, and usage tracking without being overwhelming or too sparse.

    Completeness4/5

    The tool surface covers the core workflows (handshake, list, search, activate, deactivate, add custom, metrics, usage). A minor gap is the lack of a tool to get detailed server info (beyond counts), but overall it's quite complete.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A flexible proxy that enables discovery and execution of tools across multiple Model Context Protocol (MCP) servers and JavaScript functions, reducing context size even when dealing with hundreds of tools.
      11
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Acts as a proxy for multiple MCP servers, reducing context window usage from 15,000+ tokens to ~500 tokens by dynamically loading servers on-demand and exposing only 3 tools instead of all tool definitions.
      5
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A proxy MCP server that manages multiple upstream MCP servers by grouping them and loading tool schemas on-demand, reducing LLM context usage.
      6,643 npm
      51
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A proxy MCP server that lazy-loads tools from configured servers on demand, reducing token usage and enabling mid-session server switching.
      6 npm
      MIT