Skip to content

Commit f204be8

Browse files
claudeclaude
committed
docs: add routing modes, tool quarantine docs and QA report
New feature documentation: - docs/features/routing-modes.md: direct, retrieve_tools, code_execution modes - docs/features/tool-quarantine.md: tool-level approval system with auto-approve QA report: - docs/qa/mcpproxy-qa-report-2026-03-10.html: 33 tests across REST/MCP/CLI/UI Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent f3f7520 commit f204be8

3 files changed

Lines changed: 1027 additions & 0 deletions

File tree

‎docs/features/routing-modes.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
id: routing-modes
3+
title: Routing Modes
4+
sidebar_label: Routing Modes
5+
sidebar_position: 2
6+
description: Configure how MCPProxy exposes upstream tools to AI agents
7+
keywords: [routing, modes, direct, code_execution, retrieve_tools, mcp]
8+
---
9+
10+
# Routing Modes
11+
12+
MCPProxy supports three routing modes that control how upstream MCP tools are exposed to AI agents. Each mode offers different tradeoffs between token efficiency, flexibility, and simplicity.
13+
14+
## Overview
15+
16+
| Mode | Default MCP Endpoint | Tool Exposure | Best For |
17+
|------|---------------------|---------------|----------|
18+
| `retrieve_tools` | `/mcp` | BM25 search via `retrieve_tools` + `call_tool_read/write/destructive` | Large tool sets (50+ tools), token-sensitive workloads |
19+
| `direct` | `/mcp` | All tools exposed as `serverName__toolName` | Small tool sets, simple setups, maximum compatibility |
20+
| `code_execution` | `/mcp` | `code_execution` + `retrieve_tools` for discovery | Multi-step orchestration, reduced round-trips |
21+
22+
## Configuration
23+
24+
Set the routing mode in your config file (`~/.mcpproxy/mcp_config.json`):
25+
26+
```json
27+
{
28+
"routing_mode": "retrieve_tools"
29+
}
30+
```
31+
32+
| Field | Type | Default | Values |
33+
|-------|------|---------|--------|
34+
| `routing_mode` | string | `"retrieve_tools"` | `retrieve_tools`, `direct`, `code_execution` |
35+
36+
The configured routing mode determines which tools are served on the default `/mcp` endpoint. All three modes are always available on dedicated endpoints regardless of the config setting.
37+
38+
## Dedicated Endpoints
39+
40+
Each routing mode has a dedicated MCP endpoint that is always available:
41+
42+
| Endpoint | Mode | Description |
43+
|----------|------|-------------|
44+
| `/mcp/call` | `retrieve_tools` | BM25 search via `retrieve_tools` + `call_tool` variants |
45+
| `/mcp/all` | `direct` | All upstream tools with `serverName__toolName` naming |
46+
| `/mcp/code` | `code_execution` | JavaScript orchestration via `code_execution` tool |
47+
| `/mcp` | *(configured)* | Serves whichever mode is set in `routing_mode` |
48+
49+
This means you can point different AI clients at different endpoints. For example, Claude Desktop at `/mcp` (retrieve_tools mode for token savings) and a CI/CD agent at `/mcp/all` (direct mode for simplicity).
50+
51+
## Mode Details
52+
53+
### retrieve_tools (Default)
54+
55+
The default mode uses BM25 full-text search to help AI agents discover relevant tools without exposing the entire tool catalog. This is the most token-efficient mode.
56+
57+
**Tools exposed:**
58+
- `retrieve_tools` -- Search for tools by natural language query
59+
- `call_tool_read` -- Execute read-only tool calls
60+
- `call_tool_write` -- Execute write tool calls
61+
- `call_tool_destructive` -- Execute destructive tool calls
62+
- `upstream_servers` -- Manage upstream servers (if management enabled)
63+
- `code_execution` -- JavaScript orchestration (if enabled)
64+
65+
**How it works:**
66+
1. AI agent calls `retrieve_tools` with a natural language query
67+
2. MCPProxy returns matching tools ranked by BM25 relevance
68+
3. AI agent calls the appropriate `call_tool_*` variant with the tool name
69+
70+
**When to use:**
71+
- You have many upstream servers with dozens or hundreds of tools
72+
- Token usage is a concern (only tool metadata for matched tools is sent)
73+
- You want intent-based permission control (read/write/destructive variants)
74+
75+
### direct
76+
77+
Direct mode exposes every upstream tool directly to the AI agent. Each tool is named `serverName__toolName` (double underscore separator).
78+
79+
**Tools exposed:**
80+
- Every tool from every connected, enabled, non-quarantined upstream server
81+
- Named as `serverName__toolName` (e.g., `github__create_issue`, `filesystem__read_file`)
82+
83+
**How it works:**
84+
1. AI agent sees all available tools in the tools list
85+
2. AI agent calls tools directly by their `serverName__toolName` name
86+
3. MCPProxy routes the call to the correct upstream server
87+
88+
**Tool naming:**
89+
- Separator is `__` (double underscore) to avoid conflicts with single underscores in tool names
90+
- The split happens on the FIRST `__` only, so tool names containing `__` are preserved
91+
- Descriptions are prefixed with `[serverName]` for clarity
92+
93+
**Auth enforcement:**
94+
- Agent tokens with server restrictions are enforced (access denied if token lacks server access)
95+
- Permission levels are derived from tool annotations (read-only, destructive, etc.)
96+
97+
**When to use:**
98+
- You have a small number of upstream servers (fewer than 50 total tools)
99+
- You want maximum simplicity and compatibility
100+
- AI clients that work better with a flat tool list
101+
102+
### code_execution
103+
104+
Code execution mode is designed for multi-step orchestration workflows. It exposes the `code_execution` tool with an enhanced description that includes a catalog of all available upstream tools.
105+
106+
**Tools exposed:**
107+
- `code_execution` -- Execute JavaScript/TypeScript that orchestrates upstream tools
108+
- `retrieve_tools` -- Search for tools (useful for discovery before writing code)
109+
110+
**How it works:**
111+
1. AI agent sees the `code_execution` tool with a listing of all available upstream tools
112+
2. AI agent writes JavaScript/TypeScript code that calls `call_tool(serverName, toolName, args)`
113+
3. MCPProxy executes the code in a sandboxed VM, routing tool calls to upstream servers
114+
115+
**When to use:**
116+
- Workflows that require chaining 2+ tool calls together
117+
- You want to minimize model round-trips
118+
- Complex conditional logic or data transformation between tool calls
119+
120+
**Note:** Code execution must be enabled in config (`"enable_code_execution": true`). If disabled, the `code_execution` tool appears but returns an error message directing the user to enable it.
121+
122+
## Viewing Current Routing Mode
123+
124+
### CLI
125+
126+
```bash
127+
# Status command shows routing mode
128+
mcpproxy status
129+
130+
# Doctor command shows routing mode in Security Features section
131+
mcpproxy doctor
132+
```
133+
134+
### REST API
135+
136+
```bash
137+
# Get routing mode info
138+
curl -H "X-API-Key: your-key" http://127.0.0.1:8080/api/v1/routing
139+
140+
# Response:
141+
{
142+
"routing_mode": "retrieve_tools",
143+
"description": "BM25 search via retrieve_tools + call_tool variants (default)",
144+
"endpoints": {
145+
"default": "/mcp",
146+
"direct": "/mcp/all",
147+
"code_execution": "/mcp/code",
148+
"retrieve_tools": "/mcp/call"
149+
},
150+
"available_modes": ["retrieve_tools", "direct", "code_execution"]
151+
}
152+
```
153+
154+
```bash
155+
# Status endpoint also includes routing_mode
156+
curl -H "X-API-Key: your-key" http://127.0.0.1:8080/api/v1/status
157+
```
158+
159+
## Changing Routing Mode
160+
161+
1. Edit `~/.mcpproxy/mcp_config.json`:
162+
```json
163+
{
164+
"routing_mode": "direct"
165+
}
166+
```
167+
168+
2. Restart MCPProxy:
169+
```bash
170+
pkill mcpproxy
171+
mcpproxy serve
172+
```
173+
174+
The routing mode is applied at startup and determines which MCP server instance handles the default `/mcp` endpoint. Dedicated endpoints (`/mcp/all`, `/mcp/code`, `/mcp/call`) are always available regardless of the configured mode.
175+
176+
## Tool Refresh
177+
178+
When upstream servers connect, disconnect, or update their tools:
179+
180+
- **Direct mode**: Tool list is automatically rebuilt. The AI client receives a `notifications/tools/list_changed` notification.
181+
- **Code execution mode**: The tool catalog in the `code_execution` description is refreshed.
182+
- **Retrieve tools mode**: The BM25 search index is updated.
183+
184+
## Security Considerations
185+
186+
- **Direct mode** exposes all tools upfront, which increases the initial token cost but simplifies the interaction. Use agent tokens with server restrictions to limit exposure.
187+
- **Retrieve tools mode** is the most secure by default because AI agents only see tools matching their search query.
188+
- **Code execution mode** requires explicit enablement (`enable_code_execution: true`) and runs code in a sandboxed JavaScript VM with no filesystem or network access.
189+
- All modes respect server quarantine, tool-level quarantine, and agent token permissions.

0 commit comments

Comments
 (0)