← Back to Home

Features Deep Dive

This guide explains the core concepts behind `mcpproxy`'s most powerful features: intelligent tool discovery and the security quarantine system.

Intelligent Tool Discovery & Token Optimization

A primary challenge when working with many AI tools is "context window bloat." Language models have a limited context window, and filling it with dozens or hundreds of tool function schemas is inefficient and expensive. It degrades performance and consumes tokens that could be used for more important tasks.

How MCPProxy Solves This

MCPProxy acts as a smart gateway. Instead of exposing hundreds of tools directly to the LLM, it exposes only a single, powerful tool: retrieve_tools.

1. Indexing: When `mcpproxy` starts, it connects to all your configured upstream servers and builds a local, searchable index of every available tool using the BM25 full-text search algorithm.
2. Search, Not Load: When the AI agent needs to perform a task, it doesn't see a massive list of tools. Instead, it uses the retrieve_tools function with a natural language query (e.g., "find the current price of bitcoin").
3. Relevant Results: `mcpproxy` searches its index and returns only the top most relevant tools for the query. The LLM then receives a very small, relevant list of function schemas to work with.

The Benefit: Massive Token Savings

This approach dramatically reduces the number of tokens sent in each request. Research has shown this method can lead to **~99% token savings** compared to including all tool schemas in the prompt, while simultaneously improving the accuracy of tool selection.

Security Quarantine System

As the AI agent ecosystem grows, so does the risk from malicious or poorly configured MCP servers. The quarantine system in `mcpproxy` is designed to protect you from these threats, specifically **Tool Poisoning Attacks (TPAs)**.

What are Tool Poisoning Attacks?

A TPA is a sophisticated attack where malicious instructions are hidden inside a tool's description. These instructions are often invisible to a human user but are read and executed by the LLM. A malicious tool could trick an AI agent into:

• Reading sensitive files from your computer (e.g., SSH keys, cloud credentials).
• Exfiltrating data to an attacker's server.
• Executing harmful commands on your system.
• Overriding instructions from other, trusted tools.

How the Quarantine Protects You

The quarantine system is a security-first model that puts a human in the loop for approving new tools.

1. Automatic Quarantine: Any new server added to `mcpproxy` is automatically placed into quarantine.
2. Execution Blocking: While a server is in quarantine, its tools **cannot be executed**. They are effectively in a read-only sandbox.
3. Security Analysis: You (or an LLM) can inspect the tools from a quarantined server. `mcpproxy` provides special tools like quarantine_security to list and analyze the full, unfiltered descriptions of these tools to check for TPA patterns.
4. Manual Approval: A server can only be moved out of quarantine and trusted through a deliberate, manual action: either by editing the mcp_config.json file or by using the System Tray UI. **This action can never be performed by an LLM tool call**, creating a critical security boundary.

This system allows you to safely connect to and evaluate new, untrusted MCP servers without exposing your system to risk.