mcp-dynamic-proxy 0.1.5

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 4 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
• Minimal Context: Only 4 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 4 core tools:

1. mcp_discover_servers - Discover available MCP servers by tags, search term, or category
2. mcp_list_all_servers - List all configured MCP servers without filtering
3. mcp_list_tools - List tools from a specific MCP server (loads server if needed)
4. mcp_execute_tool - Execute a tool on an MCP server (loads server if needed)

Available Tools

mcp_discover_servers

Discover available MCP servers with filtering capabilities.

Parameters:

• tags (optional): List of tags or comma-separated string (e.g., ["aws", "database"] or "aws,database")
• search (optional): Search term to filter by description or server ID
• category (optional): Category filter (e.g., "database", "documentation")

Returns: Dictionary with count and list of matching servers with their metadata

mcp_list_all_servers

List all configured MCP servers without any filtering.

Parameters: None

Returns: Dictionary with count and complete list of all servers including their id, description, tags, and category

mcp_list_tools

Get the list of tools available in a specific MCP server.

Parameters:

• server_id (required): The MCP server ID (e.g., "aws-dynamodb", "postgres")

Returns: Dictionary with server info and list of available tools with their schemas

Note: This will automatically load the server if not already loaded.

mcp_execute_tool

Execute a tool from a specific MCP server.

Parameters:

• server_id (required): The MCP server ID (e.g., "pipebot", "aws-knowledge-mcp-server")
• tool_name (required): The name of the tool to call
• arguments (required): Dictionary of arguments to pass to the tool

Returns: Dictionary with the result from the tool execution

Important Notes:

• server_id is the MCP server name, not the tool name (e.g., server_id="pipebot", tool_name="kubectl")
• Some servers provide discovery/search tools to help identify the right arguments. Check tool descriptions with mcp_list_tools first
• This will automatically load the server if not already loaded

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-knowledge-mcp-server": {
      "description": "AWS knowledge base with documentation, best practices, and service information",
      "tags": ["aws", "documentation", "cloud", "knowledge"],
      "category": "documentation",
      "command": "uvx",
      "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"]
    },
    "microsoft.docs.mcp": {
      "description": "Microsoft Learn documentation and Azure documentation access",
      "tags": ["microsoft", "azure", "documentation", "learn"],
      "category": "documentation",
      "command": "uvx",
      "args": ["fastmcp", "run", "https://learn.microsoft.com/api/mcp"]
    }
  }
}

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)

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. List all servers (get complete overview):

   User: "What MCP servers are available?"
   
   Assistant calls: mcp_list_all_servers()
   
   Response: Complete list of all configured MCP servers
   

2. Discover servers (with filtering):

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

3. List tools (from a specific server):

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

4. Execute tool:

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

License

MIT