smart-mcp-proxy 0.3.1

Smart MCP Proxy - A federating gateway for MCP servers with intelligent tool discovery

Smart MCP Proxy

Quick Start

install with pip:

pip install smart-mcp-proxy

Cursor IDE Integration

To use mcpproxy in Cursor IDE, add this configuration to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "mcpproxy",
      "env": {
        "MCPPROXY_CONFIG_PATH": "/Users/user/.cursor/mcp_proxy.json"
      }
    }
  }
}

Then create a separate ~/.cursor/mcp_proxy.json with your actual(!) MCP servers: (just an example of configuration, you can use any MCP servers you want)

{
  "mcpServers": {
    "company-mcp": {
      "command": "uvx",
      "args": ["--from", "mcp-company-python@git+https://github.com/company/mcp-company.git", "company-mcp-server"],
      "env": {
        "COMPANY_TOKEN": "${COMPANY_TOKEN}",
        "PORT": "9090"
      }
    },
    "company-docs": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Important: The mcp_proxy.json must be a different file than mcp.json to avoid circular proxy connections. The proxy configuration file has the same format as Cursor's MCP configuration but contains the actual MCP servers you want to federate.

Google ADK Integration

To use mcpproxy with Google ADK, you can integrate it using the MCPToolset:

from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters

proxy_tool = MCPToolset(
    connection_params=StdioServerParameters(
        command="mcpproxy",
        args=[],
        env={"MCPPROXY_CONFIG_PATH": "/Users/user/.cursor/mcp_proxy.json"}
    )
)

Tip for better LLM results (copy-paste into your system/dev prompt):

When you see a tool named `retrieval_tools` in the MCP tool list, call it first.  
It returns the most relevant tools for the user’s request, helping you answer more accurately and concisely.

---

A federating gateway that sits between AI agents and multiple Model Context Protocol (MCP) servers, providing intelligent tool discovery and dynamic registration.

🌐 Website: mcpproxy.app 📦 PyPI: pypi.org/project/smart-mcp-proxy 🔗 GitHub: github.com/Dumbris/mcpproxy

Features

• Flexible Routing Strategies: Two modes - DYNAMIC (tools registered on-demand) or CALL_TOOL (proxy-only execution)
• Dynamic Tool Discovery: Automatically discovers tools from multiple MCP servers
• Intelligent Search: Uses configurable embedding backends (BM25, HuggingFace, OpenAI) to find relevant tools
• One-Click Tool Access: Single retrieve_tools function that searches, registers, and exposes the top 5 most relevant tools
• FastMCP Integration: Built on FastMCP v2 for robust server runtime and client capabilities
• Persistent Indexing: SQLite + Faiss storage for fast tool lookup and change detection
• MCP Spec Compliant: Emits proper notifications/tools/list_changed events
• Flexible Dependencies: Optional dependencies for different backends to minimize install size

Architecture

┌─────────────────┐    ┌─────────────────────────────────┐    ┌─────────────────┐
│   AI Agent      │───▶│     Smart MCP Proxy             │───▶│  MCP Servers    │
│                 │    │                                 │    │                 │
│ retrieve_tools()│    │ ┌─────────────┐ ┌─────────────┐ │    │ • company-prod  │
│                 │    │ │   Indexer   │ │ Persistence │ │    │ • company-docs  │
│ tool_1()        │◀───│ │   (BM25/    │ │  (SQLite +  │ │    │ • oauth-server  │
│ tool_2()        │    │ │ HF/OpenAI)  │ │   Faiss)    │ │    │ • ...           │
│ ...             │    │ └─────────────┘ └─────────────┘ │    │                 │
└─────────────────┘    └─────────────────────────────────┘    └─────────────────┘

Quick Start

1. Installation

Choose your installation based on the embedding backend you want to use:

# Basic installation with BM25 (lexical search, no ML dependencies)
pip install smart-mcp-proxy

# Or with specific backends:
pip install smart-mcp-proxy[bm25]         # Explicit BM25 (same as basic)
pip install smart-mcp-proxy[huggingface]  # HuggingFace + vector search
pip install smart-mcp-proxy[openai]       # OpenAI embeddings + vector search
pip install smart-mcp-proxy[all]          # All backends available

# Development install
git clone https://github.com/Dumbris/mcpproxy.git
cd mcpproxy
pip install -e .[all]

The proxy will automatically check for required dependencies and provide helpful error messages if you try to use a backend without the required packages installed.

2. Start the Proxy

# Using the installed script
MCPPROXY_CONFIG_PATH=mcp_config.json mcpproxy

The proxy will:

1. Discover tools from all configured MCP servers
2. Index them using the chosen embedding backend
3. Start MCP server, by default transport is stdio, you can use MCPPROXY_TRANSPORT to change it to streamable-http or sse

Routing Strategies

Smart MCP Proxy supports two routing strategies:

DYNAMIC Mode

• Behavior: AI agent calls retrieve_tools, which searches and dynamically registers the most relevant tools as MCP tools
• Tool Registration: Tools become available in the MCP protocol after retrieve_tools call
• Client View: Sees both retrieve_tools and the registered tools (e.g., company_create_user, storage_upload_file)
• Use Case: Best for clients that can handle dynamic tool registration and notifications

CALL_TOOL Mode (Default)

• Behavior: AI agent calls retrieve_tools to discover tools, then uses call_tool to execute them
• Tool Registration: No dynamic registration - tools are executed through the proxy
• Client View: Only sees retrieve_tools and call_tool tools
• Use Case: Better for clients with tool registration limits or simpler tool management

# Set routing strategy
export MCPPROXY_ROUTING_TYPE=DYNAMIC    # or CALL_TOOL (default)

Output Truncation

To prevent context bloating from large tool outputs, you can configure output truncation:

# Truncate tool outputs to 2000 characters (disabled by default)
export MCPPROXY_TRUNCATE_OUTPUT_LEN=2000

When enabled, outputs exceeding the limit are truncated showing:

• First portion of the output
• <truncated by smart mcp proxy> marker
• Last 50 characters of the output

This helps manage token usage while preserving both the beginning and end of outputs.

Usage

Cursor IDE

See example on the top of the README.md file.

For AI Agents

DYNAMIC Mode Usage:

1. Call retrieve_tools("user management")
2. Use the returned tools directly (e.g., company_create_user)

CALL_TOOL Mode Usage:

1. Call retrieve_tools("user management")
2. Call call_tool("company_create_user", {"name": "john", "email": "[e-mail]"})

Programmatic Usage

from mcpproxy import SmartMCPProxyServer

proxy = SmartMCPProxyServer("config.json")
await proxy.start()

# Use the indexer directly
results = await proxy.indexer.search_tools("delete volume", k=3)
for result in results:
    print(f"{result.tool.name}: {result.score}")

Project Structure

mcpproxy/
├── models/
│   └── schemas.py           # Pydantic models and schemas
├── persistence/
│   ├── db.py               # SQLite operations
│   ├── faiss_store.py      # Faiss vector storage
│   └── facade.py           # Unified persistence interface
├── indexer/
│   ├── base.py             # Base embedder interface
│   ├── bm25.py             # BM25 implementation
│   ├── huggingface.py      # HuggingFace embeddings
│   ├── openai.py           # OpenAI embeddings
│   └── facade.py           # Search and indexing interface
├── server/
│   ├── config.py           # Configuration management
│   └── mcp_server.py       # FastMCP server implementation
└── utils/
    └── hashing.py          # SHA-256 utilities for change detection

Environment Variables

Variable	Values	Default	Description
MCPPROXY_ROUTING_TYPE	DYNAMIC, CALL_TOOL	CALL_TOOL	Tool routing strategy
MCPPROXY_EMBEDDER	BM25, HF, OPENAI	BM25	Embedding backend
MCPPROXY_HF_MODEL	HuggingFace model name	sentence-transformers/all-MiniLM-L6-v2	HF model
MCPPROXY_TOP_K	Integer	5	Number of tools to register
MCPPROXY_TOOLS_LIMIT	Integer	15	Maximum number of tools in active pool
MCPPROXY_TOOL_NAME_LIMIT	Integer	60	Maximum tool name length
MCPPROXY_TRUNCATE_OUTPUT_LEN	Integer	-	Truncate tool output to prevent context bloating (disabled by default)
MCPPROXY_LIST_CHANGED_EXEC	Shell command	-	External command to execute after tool changes (see Client Compatibility)
MCPPROXY_DATA_DIR	Directory path	~/.mcpproxy	Directory for database and index files
MCPPROXY_CONFIG_PATH	Path to config file	mcp_config.json	Config file location
MCPPROXY_HOST	Host to bind	127.0.0.1	Server host
MCPPROXY_PORT	Port to bind	8000	Server port
MCPPROXY_TRANSPORT	Transport to use	stdio	Transport to use
MCPPROXY_LOG_LEVEL	Log level	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
MCPPROXY_LOG_FILE	File path	-	Optional log file path
MCPPROXY_RESET_DATA	Boolean	false	Reset all data (useful when dimensions change)

Client Compatibility

MCP Tool List Refresh Workaround

This is only needed for DYNAMIC routing mode. The default CALL_TOOL routing mode doesn't require MCPPROXY_LIST_CHANGED_EXEC since tools are not dynamically registered.

Some MCP clients (like Cursor IDE) don't properly handle the standard tools/list_changed notification when new tools are registered in DYNAMIC mode. As a temporary workaround, you can configure the proxy to execute an external command after tool changes to trigger client refresh.

For Cursor IDE

Set the MCPPROXY_LIST_CHANGED_EXEC environment variable to touch the MCP configuration file:

# For macOS/Linux
export MCPPROXY_LIST_CHANGED_EXEC="touch $HOME/.cursor/mcp.json"

# For Windows (PowerShell)
$env:MCPPROXY_LIST_CHANGED_EXEC = "cmd /c copy `"$HOME\.cursor\mcp.json`" +,,"

This causes Cursor to detect the config file change and refresh its tool list.

How it Works

1. When you call retrieve_tools, the proxy registers new tools
2. Standard tools/list_changed notification is sent (proper MCP way)
3. If MCPPROXY_LIST_CHANGED_EXEC is set, the command is executed asynchronously
4. The command triggers the MCP client to refresh its tool list

Security Note

⚠️ Important: The command in MCPPROXY_LIST_CHANGED_EXEC is executed with shell privileges. Only use trusted commands and never set this variable to user-provided input.

When Not to Use

• Your MCP client properly handles tools/list_changed notifications
• You're using the proxy programmatically (not through an MCP client)
• Security policies prohibit executing external commands

This feature is disabled by default and only executes when explicitly configured.

Contributing

We welcome contributions! Please see our GitHub repository for:

• 🐛 Bug Reports: Submit an issue
• 💡 Feature Requests: Start a discussion
• 🔧 Pull Requests: Fork the repo and submit a PR

Development Setup

git clone https://github.com/Dumbris/mcpproxy.git
cd mcpproxy
pip install -e .[dev,all]
pytest tests/

License

This project is licensed under the MIT License - see the LICENSE file for details.