Provides security isolation for upstream MCP servers by running them in Docker containers, creating a quarantine against malicious tool poisoning attacks.
Enables AI agents to bypass OpenAI's 128-function limit by federating multiple MCP servers and using intelligent tool retrieval to reduce token consumption.
The demo above shows the embedded web UI. The MCPProxy core is a single binary for macOS, Linux, and Windows — the web UI ships inside it, with no extra service to run. On macOS, an optional menu‑bar app adds one‑click convenience (start/stop, server health, quarantine, logs).
Scale beyond API limits – Federate hundreds of MCP servers while bypassing Cursor's 40-tool limit and OpenAI's 128-function cap.
Save tokens & accelerate responses – Agents load just one retrieve_tools function instead of hundreds of schemas. Research shows ~99 % token reduction with 43 % accuracy improvement.
Advanced security protection – Automatic quarantine blocks Tool Poisoning Attacks until you manually approve new servers.
Pluggable security scanners – Run Snyk, Semgrep, Trivy, Cisco, and other Docker-based scanners against quarantined servers before you approve them; findings are normalized to SARIF with a composite risk score. See Security scanner plugins.
Works offline & cross-platform – A single core binary for macOS (Intel & Apple Silicon), Windows (x64 & ARM64), and Linux (x64 & ARM64), with the web UI embedded. macOS additionally ships an optional menu-bar app.
Related MCP server: proxy-mcp
macOS (Recommended - DMG Installer):
Download the latest DMG installer for your architecture:
Apple Silicon (M1/M2): Download DMG → mcpproxy-*-darwin-arm64.dmg
Intel Mac: Download DMG → mcpproxy-*-darwin-amd64.dmg
Windows (Recommended - Installer):
Download the latest Windows installer for your architecture:
x64 (64-bit): Download Installer → mcpproxy-setup-*-amd64.exe
ARM64: Download Installer → mcpproxy-setup-*-arm64.exe
The installer automatically:
Installs both mcpproxy.exe (core server) and mcpproxy-tray.exe (system tray app) to Program Files
Adds MCPProxy to your system PATH for command-line access
Creates Start Menu shortcuts
Supports silent installation: .\mcpproxy-setup.exe /VERYSILENT
Alternative install methods:
macOS (Homebrew):
# macOS — GUI tray app (recommended):
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy
# macOS / Linux — headless CLI only:
brew install smart-mcp-proxy/mcpproxy/mcpproxyThe cask installs the menu-bar app (bundles the CLI); the formula is the CLI binary only. Both update via brew upgrade.
Linux (Debian/Ubuntu) — apt repository, auto-updates via apt upgrade:
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
| sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
| sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
sudo apt update && sudo apt install mcpproxyLinux (Fedora / RHEL / Rocky / AlmaLinux) — dnf repository, auto-updates via dnf upgrade:
sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
# Fedora 41+ (dnf5): sudo curl -fsSL https://rpm.mcpproxy.app/mcpproxy.repo -o /etc/yum.repos.d/mcpproxy.repo
sudo dnf install -y mcpproxyArch Linux (AUR): mcpproxy-bin
yay -S mcpproxy-bin
# or
git clone https://aur.archlinux.org/mcpproxy-bin.git && cd mcpproxy-bin && makepkg -siThe apt and dnf packages ship a hardened systemd unit and start the service automatically. Repository signing key fingerprint: 3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B.
For one-off .deb / .rpm downloads (air-gapped installs), grab them from the latest release.
Manual download (all platforms):
Prerelease Builds (Latest Features):
Want to try the newest features? Download prerelease builds from the next branch:
Go to GitHub Actions
Click the latest successful "Prerelease" workflow run
Download from Artifacts:
dmg-darwin-arm64 (Apple Silicon Macs)
dmg-darwin-amd64 (Intel Macs)
versioned-linux-amd64, versioned-windows-amd64 (other platforms)
Note: Prerelease builds are signed and notarized for macOS but contain cutting-edge features that may be unstable.
macOS: Intel | Apple Silicon
Anywhere with Go 1.25+:
go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latestmcpproxy serve # starts HTTP server on :8080 and shows trayCreate or edit ~/.mcpproxy/mcp_config.json:
{
"listen": "127.0.0.1:8080",
"mcpServers": [
{ "name": "local-python", "command": "python", "args": ["-m", "my_server"], "protocol": "stdio", "enabled": true },
{ "name": "remote-http", "url": "http://localhost:3001", "protocol": "http", "enabled": true }
]
}See Configuration and Upstream Servers for the full reference.
📖 Complete Setup Guide - Detailed instructions for Cursor, VS Code, Claude Desktop, and Goose
Open Cursor Settings
Click "Tools & Integrations"
Add MCP server
"MCPProxy": {
"type": "http",
"url": "http://localhost:8080/mcp/"
}Once connected, your agent sees a handful of built-in MCPProxy tools instead of hundreds of upstream schemas. A typical session has three beats — discover, call, audit — plus an optional preflight gate for unattended automations.
The agent asks for what it needs in plain keywords via retrieve_tools:
{ "query": "create github issue", "limit": 5 }MCPProxy runs a BM25 search across every connected server and returns only the top-ranked matches — each with a call_with hint recommending the right call variant for its annotations:
{
"tools": [
{ "name": "github:create_issue", "score": 0.89, "call_with": "call_tool_write" },
{ "name": "gitlab:create_issue", "score": 0.72, "call_with": "call_tool_write" }
]
}This is where the token savings come from: the schemas of the hundreds of tools the agent didn't need never enter its context. The agent loads full schemas on demand with describe_tool (batch up to 5 ids) only for the tools it's about to use.
The agent executes the tool through the variant matching its intent (call_tool_read, call_tool_write, or call_tool_destructive), addressing it as server:tool:
{
"name": "github:create_issue",
"args_json": "{\"repo\": \"acme/api\", \"title\": \"Bug report\"}",
"intent": { "operation_type": "write", "reason": "Filing bug per user request" }
}MCPProxy validates the intent against the tool's annotations (a "read" call can't reach a destructive tool), checks quarantine and approval state, and scans arguments and responses for sensitive data before anything leaves the machine.
Every call lands in the local Activity Log with a request ID, so you can reconstruct exactly what an agent did:
mcpproxy activity list # everything, newest first
mcpproxy activity list --request-id <id> # one workflow, correlatedFor recurring headless jobs (cron, CI, n8n), don't let the agent discover a missing tool the expensive way. One preflight command checks that every required tool is ready — without contacting any upstream server — and reports exactly why when it isn't (server quarantined, tool changed since approval, OAuth expired, typo'd id):
mcpproxy tools preflight gh-ops:sync_issues slack:post_message --wait 10s
case $? in
0) run-agent-session ;; # all ready — go
10) exit 75 ;; # transient (server starting) — let the next cron tick retry
11) page-operator ;; # blocked — someone must approve / enable / log in
12) fail-pipeline ;; # unknown tool id — the automation itself is misconfigured
esacSee Required-Tools Preflight for the full reason taxonomy, REST endpoint, and GitHub Actions / n8n recipes.
MCPProxy works with HTTP by default for easy setup. HTTPS is optional and primarily useful for production environments or when stricter security is required.
💡 Note: Most users can stick with HTTP (the default) as it works perfectly with all supported clients including Claude Desktop, Cursor, and VS Code.
1. Enable HTTPS (choose one method):
# Method 1: Environment variable
export MCPPROXY_TLS_ENABLED=true
mcpproxy serve
# Method 2: Config file
# Edit ~/.mcpproxy/mcp_config.json and set "tls.enabled": true2. Trust the certificate (one-time setup):
mcpproxy trust-cert3. Use HTTPS URLs:
MCP endpoint: https://localhost:8080/mcp
Web UI: https://localhost:8080/ui/
For Claude Desktop, add this to your claude_desktop_config.json:
HTTP (Default - Recommended):
{
"mcpServers": {
"mcpproxy": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8080/mcp"
]
}
}
}HTTPS (With Certificate Trust):
{
"mcpServers": {
"mcpproxy": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://localhost:8080/mcp"
],
"env": {
"NODE_EXTRA_CA_CERTS": "~/.mcpproxy/certs/ca.pem"
}
}
}
}Automatic generation: Certificates created on first HTTPS startup
Multi-domain support: Works with localhost, 127.0.0.1, ::1
Trust installation: Use mcpproxy trust-cert to add to system keychain
Certificate location: ~/.mcpproxy/certs/ (ca.pem, server.pem, server-key.pem)
Certificate trust issues:
# Re-trust certificate
mcpproxy trust-cert --force
# Check certificate location
ls ~/.mcpproxy/certs/
# Test HTTPS connection
curl -k https://localhost:8080/api/v1/statusClaude Desktop connection issues:
Ensure NODE_EXTRA_CA_CERTS points to the correct ca.pem file
Restart Claude Desktop after config changes
Verify HTTPS is enabled: mcpproxy serve --log-level=debug
We welcome issues, feature ideas, and PRs!
make dev-setup # Install swag, frontend deps, Playwright
brew install prek # Install pre-commit hook runner (or: uv tool install prek)
prek install # Install pre-commit hooks
prek install --hook-type pre-push # Install pre-push hooksWe use prek to catch issues before they reach CI:
Hook | Stage | What it does |
| pre-commit | Auto-formats staged Go files |
| pre-commit | Removes trailing whitespace |
| pre-commit | Ensures files end with newline |
| pre-commit | Detects merge conflict markers |
| pre-push | Fails if OpenAPI spec is out of date |
| pre-push | Verifies the project compiles |
Run hooks manually: prek run --all-files
make build # Build frontend + backend
make swagger # Regenerate OpenAPI spec
make test # Unit tests
make test-e2e # E2E tests
make lint # Run lintersExecute a DESTRUCTIVE tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results. DECISION RULE: Use this when the tool name contains: delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. Examples: delete_repo, remove_user, drop_table, revoke_access, clear_cache, terminate_session. Use for irreversible or high-impact operations.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments to pass to the upstream tool as a native JSON object. Refer to the tool's inputSchema from retrieve_tools for required parameters. Example: {"path": "src/index.ts", "limit": 20}. This is the preferred parameter — it eliminates JSON escaping overhead. Use 'args_json' only if your client cannot produce nested JSON objects. | |
| name | Yes | Tool name in format 'server:tool' (e.g., 'github:delete_repo'). CRITICAL: You MUST use exact names from retrieve_tools results - do NOT guess or invent server names. Unknown servers will fail. | |
| args_json | No | Legacy: arguments as a pre-serialized JSON string. Prefer the 'args' parameter instead — it accepts a native JSON object and eliminates escaping overhead. If both are provided, 'args_json' wins for backward compatibility. | |
| intent_reason | No | Why is this deletion needed? Provide justification like 'User confirmed cleanup' or 'Removing obsolete data'. | |
| intent_data_sensitivity | No | Classify data being deleted: public, internal, private, or unknown. Important for tracking destructive operations on sensitive data. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true; description adds context that operations are irreversible/high-impact and emphasizes using exact names from retrieve_tools. No contradiction, but doesn't detail further behavioral traits like auth needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (3 sentences), front-loaded, and uses clear structure with numbered steps and a keyword list. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers workflow, decision rule, and required parameter. Missing some context like conflict resolution between args and args_json, but schema handles that. Adequate for a meta-tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with detailed descriptions for all 5 parameters. The description adds no additional parameter information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes a destructive tool and provides a decision rule listing keywords for when to use, with examples. It distinguishes from siblings like call_tool_read and call_tool_write.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a workflow (call retrieve_tools first) and a decision rule based on tool name keywords, explicitly guiding when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a READ-ONLY tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results. DECISION RULE: Use this when the tool name contains: search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. Examples: search_files, get_user, list_repositories, query_database, find_issues, check_status. This is the DEFAULT choice when unsure - most tools are read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments to pass to the upstream tool as a native JSON object. Refer to the tool's inputSchema from retrieve_tools for required parameters. Example: {"path": "src/index.ts", "limit": 20}. This is the preferred parameter — it eliminates JSON escaping overhead. Use 'args_json' only if your client cannot produce nested JSON objects. | |
| name | Yes | Tool name in format 'server:tool' (e.g., 'github:get_user'). CRITICAL: You MUST use exact names from retrieve_tools results - do NOT guess or invent server names. Unknown servers will fail. | |
| args_json | No | Legacy: arguments as a pre-serialized JSON string. Prefer the 'args' parameter instead — it accepts a native JSON object and eliminates escaping overhead. If both are provided, 'args_json' wins for backward compatibility. | |
| intent_reason | No | Why is this tool being called? Provide context like 'User asked to check status' or 'Gathering data for report'. | |
| intent_data_sensitivity | No | Classify data being accessed: public, internal, private, or unknown. Helps track sensitive data access patterns. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims the tool is read-only ('READ-ONLY tool'), but the annotations set destructiveHint=true, indicating potential destructive behavior. This is a clear contradiction. The description does not address or reconcile this inconsistency, nor does it disclose other behavioral traits like authorization needs or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear workflow and decision rule, front-loading the purpose. However, it is somewhat lengthy due to the list of keywords and examples. It could be slightly more concise, but the structure is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no output schema, contradictory annotations), the description covers usage context well but fails to address the annotation contradiction or describe return values. It provides examples and decision rules but is incomplete in behavioral transparency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond what the schema provides. The parameters are fully described in the input schema itself, so the description adds no extra value for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a READ-ONLY tool' and provides a specific verb ('execute') and resource ('tool'). It distinguishes from siblings by specifying it's for tools whose names match read-related patterns like search, get, list, etc. The default choice statement further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines: a workflow (call retrieve_tools first, use exact name), a decision rule with a comprehensive list of name patterns, examples, and a default choice instruction. It implicitly excludes destructive/write tools without naming them directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a STATE-MODIFYING tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results. DECISION RULE: Use this when the tool name contains: create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. Examples: create_issue, update_file, send_message, add_comment, set_status, edit_page. Use only when explicitly modifying state.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments to pass to the upstream tool as a native JSON object. Refer to the tool's inputSchema from retrieve_tools for required parameters. Example: {"path": "src/index.ts", "limit": 20}. This is the preferred parameter — it eliminates JSON escaping overhead. Use 'args_json' only if your client cannot produce nested JSON objects. | |
| name | Yes | Tool name in format 'server:tool' (e.g., 'github:create_issue'). CRITICAL: You MUST use exact names from retrieve_tools results - do NOT guess or invent server names. Unknown servers will fail. | |
| args_json | No | Legacy: arguments as a pre-serialized JSON string. Prefer the 'args' parameter instead — it accepts a native JSON object and eliminates escaping overhead. If both are provided, 'args_json' wins for backward compatibility. | |
| intent_reason | No | Why is this modification needed? Provide context like 'User requested update' or 'Fixing reported issue'. | |
| intent_data_sensitivity | No | Classify data being modified: public, internal, private, or unknown. Helps track sensitive data changes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds that this is a state-modifying caller. It explains the meta-calling nature but does not detail error handling or failure modes, which would further enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a workflow, decision rule, and examples. It is slightly verbose but efficient in conveying necessary information. Could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a meta-caller, the description covers workflow, parameter usage, and decision logic. However, it omits what the tool returns (varies by upstream tool) and potential error scenarios, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds extra guidance: preferring 'args' over 'args_json', the 'server:tool' format for 'name', and rationale for intent parameters. This goes beyond the schema's baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a STATE-MODIFYING tool', specifies a decision rule based on tool name verbs, and uses examples. This differentiates it from sibling tools like call_tool_destructive and call_tool_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides a workflow (retrieve_tools first, use exact name), a decision rule listing verb triggers, and cautions against guessing server names. This fully guides the agent on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
📋 List all available MCP registries. Use this FIRST to discover which registries you can search with the 'search_servers' tool. Each registry contains different collections of MCP servers that can be added as upstreams.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds that it lists registries. However, the destructiveHint=true in annotations contradicts the non-destructive nature of listing, which is not addressed in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with an emoji, front-loaded with purpose, no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, the description fully explains its purpose and usage context relative to other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description does not need to add parameter info; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Describes a specific verb ('list') and resource ('available MCP registries'), and distinguishes itself from sibling 'search_servers' by recommending its prior use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this FIRST' and explains its relationship with 'search_servers', but does not provide when-not-to-use guidance for other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Security quarantine management for MCP servers and tools. Review and manage quarantined servers and tools to prevent Tool Poisoning Attacks (TPAs). Supports server-level quarantine and tool-level approval for individual tool description/schema changes. NOTE: Unquarantining servers is only available through manual config editing or system tray UI for security.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Server name (required for inspect_quarantined, quarantine_server, inspect_tools, approve_tool, approve_all_tools) | |
| operation | Yes | Security operation: list_quarantined, inspect_quarantined, quarantine_server, inspect_tools, approve_tool, approve_all_tools | |
| tool_name | No | Tool name (required for approve_tool operation) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and description mentions quarantining/approving as destructive actions. The NOTE adds transparency about unquarantining limitations. However, details on side effects of each operation are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences plus a note, front-loaded with purpose. Every sentence adds necessary context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers overall purpose but lacks per-operation details (e.g., return values, what each operation does). With no output schema, more specific descriptions for each operation would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description enumerates operations but adds no additional semantic depth beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool manages quarantine of MCP servers and tools to prevent TPAs, with specific operations listed. It distinguishes from siblings like call_tool_*, but does not explicitly contrast with all alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like call_tool_read or retrieve_tools. The NOTE on unquarantining is a constraint but does not help choose among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve paginated data when mcpproxy indicates a tool response was truncated. Use the cache key provided in truncation messages to access the complete dataset with pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Cache key provided by mcpproxy when a response was truncated (e.g. 'Use read_cache tool: key="abc123def..."') | |
| limit | No | Maximum number of records to return per page (default: 50, max: 1000) | |
| offset | No | Starting record offset for pagination (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description describes a read-only retrieval operation, but annotations declare destructiveHint=true, creating a contradiction. Beyond this, the description does not add detail about pagination behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and usage, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic trigger and parameter source, but lacks information about return format (no output schema) and does not resolve the contradiction between read-only description and destructive annotation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds only marginal context (e.g., where to find the key). The description does not explain limit/offset beyond their defaults and max.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves paginated data when a response is truncated, using a cache key. It distinguishes from unrelated siblings by specifying a unique trigger condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool (after truncation) and how to obtain the cache key, but does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Results include 'annotations' (tool behavior hints like destructiveHint) and 'call_with' recommendation indicating which tool variant to use (call_tool_read/write/destructive). Then use the recommended variant with an 'intent' parameter. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers.
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | Enable debug mode with detailed scoring and ranking explanations (default: false) | |
| limit | No | Maximum number of tools to return (default: configured tools_limit, max: 100) | |
| query | Yes | Natural language description of what you want to accomplish. Be specific about your task (e.g., 'create a new GitHub repository', 'get weather for London', 'query SQLite database for users'). The search will find the most relevant tools across all connected servers. | |
| explain_tool | No | When debug=true, explain why a specific tool was ranked low (format: 'server:tool') | |
| include_stats | No | Include usage statistics for returned tools (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations provide readOnlyHint=true (read-only) and destructiveHint=true (contradictory internally), the description explains the tool's behavior well: it performs BM25 search, excludes quarantined servers, and returns results with annotations and call_with recommendations. It does not contradict annotations but adds context beyond them. The internal annotation contradiction is not reflected in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured and front-loaded with the most critical instruction. Each sentence provides useful information (usage guidance, search algorithm, result contents, exclusions, server addition). While it could be slightly more concise, the structured information justifies the length for an important tool discovery mechanism.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema, annotations present), the description covers purpose, usage guidelines, behavioral details, parameter usage, and related tools. It partially covers output by mentioning 'annotations' and 'call_with' recommendations. It could mention pagination or error handling, but the existing information is largely sufficient for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context for parameters: it explains that 'query' should be a natural language description with examples, that 'debug' enables ranking explanations, and how 'explain_tool' works in debug mode. This adds value beyond what the schema provides, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'CALL THIS FIRST to discover relevant tools!' It specifically identifies the action (retrieve tools), the resource (tools across all MCP servers), and the method (BM25 full-text search). It distinguishes itself from sibling tools by being the primary discovery mechanism and explicitly advises using it before calling any specific tools. The verb 'retrieve' combined with the explanatory text provides excellent clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Always use this before attempting to call any specific tools' and 'Use natural language to describe what you want to accomplish.' It also tells when not to use this tool (quarantined servers) and directs to alternatives: 'Use 'quarantine_security' tool to examine and manage quarantined servers' and 'Use 'list_registries' then 'search_servers' to find and add new MCP servers.' This clearly differentiates when to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 Discover MCP servers from known registries with repository type detection. Search and filter servers from embedded registry list to find new MCP servers that can be added as upstreams. Features npm/PyPI package detection for enhanced install commands. WORKFLOW: 1) Call 'list_registries' first to see available registries, 2) Use this tool with a registry ID to search servers. Results include server URLs and repository information ready for direct use with upstream_servers add command.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter servers by tag/category (if supported by registry) | |
| limit | No | Maximum number of results to return (default: 10, max: 50) | |
| search | No | Search term to filter servers by name or description (case-insensitive) | |
| registry | Yes | Registry ID or name to search (e.g., 'smithery', 'mcprun', 'pulse'). Use 'list_registries' tool first to see available registries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is for searching and discovering, implying read-only behavior. However, annotations include both readOnlyHint=true and destructiveHint=true, which contradict each other and the description. This contradiction severely undermines behavioral transparency, as it's unclear whether the tool is safe or destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, with a clear structure: a purpose statement followed by a workflow. It could be more concise (e.g., removing the emoji or slightly redundant phrasing), but overall it is focused and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains that results include server URLs and repository information ready for use with upstream_servers. This is sufficient for the agent to understand the return value. However, it lacks details on pagination or limits, which are partially covered by the limit parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context about workflow but does not provide additional meaning for the parameters beyond what the schema offers. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to discover and search for MCP servers from known registries. It specifies the verb ('discover', 'search'), resource ('MCP servers'), and the outcome (finding servers to add as upstreams). It also distinguishes itself from sibling tools like list_registries and upstream_servers by describing the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: '1) Call 'list_registries' first to see available registries, 2) Use this tool with a registry ID to search servers.' This tells the agent when and how to use the tool, including prerequisites and follow-up actions with upstream_servers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage upstream MCP servers - add, remove, update, and list servers. Includes Docker isolation configuration and connection status monitoring. SECURITY: Newly added servers are automatically quarantined to prevent Tool Poisoning Attacks (TPAs). Use 'quarantine_security' tool to review and manage quarantined servers. NOTE: Unquarantining servers is only available through manual config editing or system tray UI for security.
Docker Isolation: Use 'isolation_json' parameter to configure per-server Docker images, CPU/memory limits, and network isolation. Example: {"enabled": true, "image": "node:20", "network_mode": "bridge"}.
SMART PATCHING (update/patch): Uses deep merge - only specify fields you want to change. Omitted fields are PRESERVED, not removed. Examples:
Enable server: {"operation": "patch", "name": "my-server", "enabled": true} - only enabled changes
Enable isolation: {"operation": "patch", "name": "my-server", "isolation_json": "{"enabled": true}"} - enables isolation with defaults
Update image: {"operation": "patch", "name": "my-server", "isolation_json": "{"image": "python:3.12"}"} - other isolation fields preserved
Add env var: env_json merges with existing vars
Replace args: args_json replaces entirely (arrays not merged)
Remove field: use 'null' (e.g., isolation_json: "null" removes isolation)
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Server URL for HTTP/SSE servers (e.g., 'http://localhost:3001') | |
| name | No | Server name (required for add/remove/update/patch/tail_log operations) | |
| lines | No | Number of lines to tail from server log (default: 50, max: 500) - used with tail_log operation | |
| command | No | Command to run for stdio servers (e.g., 'uvx', 'python') | |
| enabled | No | Whether server should be enabled (default: true) | |
| env_json | No | Environment variables for stdio servers as JSON object (e.g., '{"API_KEY": "value"}'). For update/patch: MERGES with existing vars (new keys added, existing keys updated). | |
| protocol | No | Transport protocol: stdio, http, sse, streamable-http, auto (default: auto-detect) | |
| args_json | No | Command arguments for stdio servers as a JSON array of strings (e.g., '["mcp-server-sqlite", "--db-path", "/path/to/db"]'). For update/patch: REPLACES all existing args (arrays are not merged). | |
| operation | Yes | Operation: list, add, remove, update, patch, tail_log. 'update' and 'patch' use smart merge - only specified fields change, others preserved. For quarantine operations, use the 'quarantine_security' tool. | |
| oauth_json | No | OAuth config as JSON object. MERGES with existing settings. Use 'null' to remove OAuth entirely. Fields: client_id, client_secret, scopes (array - replaces). | |
| headers_json | No | HTTP headers for authentication as JSON object (e.g., '{"Authorization": "Bearer token"}'). For update/patch: MERGES with existing headers (new keys added, existing keys updated). | |
| isolation_json | No | Docker isolation config as JSON object. MERGES with existing settings - only provided fields change. Use 'null' to remove isolation entirely. Example: '{"image": "python:3.12"}' updates only the image. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: automatic quarantine for security, Docker isolation, smart merging for updates, and that unquarantining requires manual config. Annotations partially cover safety, but description adds critical context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with summary, security note, Docker isolation, and smart patching examples. Slightly lengthy but each section adds value. Front-loaded with most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers tool complexity: all 12 parameters, 6 operations, security interactions, merging rules, and integration with quarantine tool. No output schema, so not required. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value with detailed operation-specific behavior, merging rules, and examples (e.g., env_json merge, args_json replace). Not perfect but exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages upstream MCP servers with specific operations (add, remove, update, list). It distinguishes from siblings like quarantine_security and search_servers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool vs alternatives (e.g., quarantine operations go to quarantine_security). Explains each operation's use and provides examples for smart patching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: three call variants for execution, registry listing, security management, cache reading, tool discovery, server search, and server management. No overlap or ambiguity between tools.
Most tools follow a consistent verb_noun snake_case pattern (e.g., list_registries, read_cache). The three call_tool_* variants have a slightly different structure but are internally consistent. Minor deviation prevents a perfect score.
9 tools is well-scoped for an MCP proxy server. The set covers discovery, execution, management, security, and pagination without being overwhelming or sparse.
The tool surface fully covers the domain: tool discovery, execution (read/write/destructive), server management, server search, security quarantine, and truncated response handling. No obvious gaps for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
The MCP server that vets MCP servers: identity, risk grade and per-tool risk before you install.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/smart-mcp-proxy/mcpproxy-go'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
