DynamicMCPProxy
Provides tools for managing Docker containers, images, and Docker-related operations.
Provides tools for managing GitHub repositories, issues, pull requests, and other GitHub resources.
Provides tools for interacting with Slack, including sending messages, managing channels, and more.
Provides tools for interacting with Stripe, including payment processing, customer management, and subscription handling.
Provides tools for managing infrastructure with Terraform, including state management, plan execution, and resource operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DynamicMCPProxy handshake: Python, FastAPI, Postgres for building a REST API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 evictionRelated 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.shThe 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 syncConfigure
Copy the example config:
cp proxy_config.json.example proxy_config.jsonSet 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.jsonAdd 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 |
| Context handshake — activates relevant servers |
| Currently mounted servers + tool counts |
| Browse catalogue |
| Mount a server (deferred by default) |
| Generate & mount server from OpenAPI/GraphQL (lean=True uses LAP for smaller specs) |
| Free up tool budget |
| Add an ad-hoc server (SSE/HTTP only) |
| List exact names of all mounted tools |
| Diagnostic: Full dump of current tool registry |
| Live memory/CPU/uptime metrics |
| Server usage counts for self-evolving ranking |
| Reset usage stats (for testing/re-baselining) |
MCP Resources
URI | Description |
| Static metadata (version, capabilities) |
| Live health (uptime, memory, active tools) |
| Full server inventory (active + available) |
MCP Discovery Surface
MCP Method | What the AI Sees |
| Minimal |
| Live health, proxy info, server inventory |
|
|
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 the40mcpengine 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 .envKeys 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 useguardrails_enabled— prompt-injection scanning + result size capsreceipts_enabled— write JSONL receipts toaudit_log_pathwithrun_id,span_id, caller, status, latency, server/tool names, and privacy-safe argument summariesotel_enabled— optionally mirror receipt events into OpenTelemetry whenopentelemetry-*packages are installed; JSONL receipts continue to work without those optional packagesotel_capture_content— defaults tofalse; 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_idandspan_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_pathto your RSA public key PEMHMAC API key — set
hmac_api_key(passed viaX-API-Keyheader)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 payloadsRate 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-thinkingonly when hitting a complex logic gate, then swap it fordockerorterraformduring 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.pyRun Tests
uv run pytest tests/ -vOptional 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-mortemscodebase_insights/— module-level hidden knowledgearchitectural_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 startedCONTEXT.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 decisionsresearch/— 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 |
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 | |
Replaces all tools with 3–4 generic | 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 | 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 whatproxy_handshake({ tech_stack, task_description })does today.No fork required — add servers to
catalogue.jsonoruser.catalogue.json; the matcher and budget enforcement are automatic.
Inspiration
Available Tools
13 toolsproxy_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
Scored across 13 tools
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.
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.
13 tools is well-scoped for a proxy management server, covering setup, discovery, activation, inspection, and usage tracking without being overwhelming or too sparse.
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
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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.11ISC
- AlicenseNot gradedqualityDmaintenanceActs 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.5GPL 3.0
- AlicenseNot gradedqualityDmaintenanceA proxy MCP server that manages multiple upstream MCP servers by grouping them and loading tool schemas on-demand, reducing LLM context usage.6,643 npm51MIT
- AlicenseNot gradedqualityDmaintenanceA proxy MCP server that lazy-loads tools from configured servers on demand, reducing token usage and enabling mid-session server switching.6 npmMIT