mcp-dynamic-proxy 0.1.1

Dynamic MCP proxy server with progressive discovery and lazy loading

MCP Dynamic Proxy

A dynamic MCP (Model Context Protocol) proxy server that provides progressive discovery and lazy loading of MCP servers, dramatically reducing initial context size from 20-300 tools to just 3 core tools.

Features

• Progressive Discovery: Discover MCP servers by tags, category, or search term without loading them
• Lazy Loading: Load MCP servers only when needed
• Intelligent Caching: TTL-based connection caching with automatic cleanup
• Minimal Context: Only 3 core discovery/execution tools exposed initially instead of hundreds
• Full MCP Protocol: Uses official MCP SDK for end-to-end protocol support

Architecture

Assistant (Cursor) -MCP-> MCP Dynamic Proxy -MCP-> MCP Servers (AWS, PostgreSQL, etc.)

The proxy exposes only 3 core tools:

1. mcp_discover_servers - Discover available MCP servers
2. mcp_list_tools - List tools from a specific MCP server
3. mcp_execute_tool - Execute a tool on an MCP server

Installation

Prerequisites

• Python 3.12+

Setup

Install dependencies (requires Python 3.12 available on PATH):

python3.12 -m pip install -e .

For development:

python3.12 -m pip install -e ".[dev]"

Configuration

Create a config/mcp.json file with your MCP server configurations:

{
  "version": "1.0",
  "mcpServers": {
    "aws-dynamodb": {
      "description": "AWS DynamoDB operations",
      "tags": ["aws", "database", "nosql"],
      "category": "database",
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "lazy_load": true,
      "cache_ttl": 1800
    }
  }
}

Configuration Fields

• description: Human-readable description of the server
• tags: List of tags for filtering (e.g., ["aws", "database"])
• category: Server category (e.g., "database", "documentation")
• command: Command to start the MCP server
• args: Arguments for the command
• env: Optional environment variables (supports ${VAR_NAME} expansion)
• lazy_load: Whether to load server on-demand (default: true)
• cache_ttl: Cache TTL in seconds (default: 3600)

Usage

Running the Server

Run the MCP proxy server:

uvx mcp-dynamic-proxy

Or with custom config path:

MCP_CONFIG_PATH=/path/to/config.json uvx mcp-dynamic-proxy

Configuration for Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "mcp-dynamic-proxy": {
      "command": "uvx",
      "args": ["mcp-dynamic-proxy"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/config/mcp.json"
      }
    }
  }
}

Example Workflow

1. Discover servers:

   User: "Show me database servers"
   
   Assistant calls: mcp_discover_servers(tags=["database"])
   
   Response: List of database MCP servers
   

2. List tools:

   Assistant calls: mcp_list_tools(server_id="aws-dynamodb")
   
   Response: List of available tools (query, scan, put_item, etc.)
   

3. Execute tool:

   Assistant calls: mcp_execute_tool(
     server_id="aws-dynamodb",
     tool_name="query",
     arguments={"table": "users", "key": {"id": "123"}}
   )
   
   Response: Tool execution result
   

Documentation

• API Documentation - Detailed API reference with request/response schemas for all MCP tools
• Troubleshooting Guide - Common issues, solutions, and debugging techniques
• Architecture - System design and component interactions

Development

Running Tests

Run the test suite with pytest:

# Install dev dependencies
python3.12 -m pip install -e ".[dev]"

# Run tests
python3.12 -m pytest

# Run tests with coverage
python3.12 -m pytest --cov=src/mcp_dynamic_proxy --cov-report=html

Project Structure

mcp-dynamic-proxy/
├── src/
│   └── mcp_dynamic_proxy/
│       ├── server.py              # FastMCP entry point
│       ├── config.py              # Configuration loading
│       ├── registry.py            # Server registry
│       ├── core/                  # Manager, pool, models, rate limiting
│       ├── resilience/            # Circuit breaker, retry primitives
│       └── tools/                 # Core tool implementations (discover, list, execute)
├── config/
│   └── mcp.json                   # Server configurations
└── ARCHITECTURE.md                # System architecture

Benefits

Metric	Before (Static)	After (Dynamic)	Improvement
Initial Context	20-40 tools	3 tools	-85%
Startup Tokens	~10k-15k	~500-1k	-90%
Startup Time	5-10s	<1s	-80%
Memory Usage	All servers	Active servers only	-70%

License

MIT