Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/guides/diagnose-unavailable-tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ Preflight reads local proxy state; it does **not** contact the upstream or guara
| `server_initializing` or another retryable reason (exit `10`) | Read the action/detail; allow a short retry with `--wait 10s`. If it persists, inspect the server's connection error and logs. |
| `server_quarantined`, `tool_pending_approval`, `tool_changed` (usually exit `11`) | Inspect the held definitions in step 3. |
| Disabled server or tool; configuration policy denial | Confirm whether the restriction is intentional. Use the server/Tools view to identify it before enabling anything. |
| `tool_blocked_by_user` (exit `11`) | The tool was disabled explicitly. Inspect the Tools view and enable it only if that decision should be reversed. |
| `oauth_required` or an upstream authentication problem | Authenticate the upstream through its server page. See [OAuth authentication](/features/oauth-authentication). |
| `not_found` (exit `12`) | Verify the exact name and server entry. An agent-visible `not_found` can also mean its access scope hides the tool. |

Expand Down Expand Up @@ -98,6 +99,8 @@ For `retrieve_tools` mode, ask the agent:

If retrieval returns no match despite client access being allowed, try a short query describing the tool's operation. Check that discovery has completed and the server's Tools view lists the expected tool. If the agent does not attempt MCPProxy at all, use [Agent instructions](/features/agent-instructions). In other routing modes, use their [documented call surface](/features/routing-modes).

When a tool is disabled, ordinary retrieval can return a different match instead. A direct attempt may return `TOOL_BLOCKED` with a hint to retrieve with `include_disabled:true`. If the client exposes that retrieval option, use it; otherwise use preflight and the Tools view to identify the hold before changing its state.

If a call was attempted, inspect Activity:

```bash
Expand Down Expand Up @@ -126,4 +129,4 @@ Repeat the **same original request in the same client**, with the intended profi

If it still fails, save the sanitized error, MCPProxy version, timestamp/request ID, routing mode and preflight reason when [reporting an issue](https://github.com/smart-mcp-proxy/mcpproxy-go/issues). A ready preflight alone is not proof of a successful recovery.

*Validation: 22 October 2026, MCPProxy v0.71.1 on macOS. Quarantine, approval, transient initialization, tool disable/re-enable, unknown ID, invalid arguments and successful retry were checked in an isolated instance. Maintained by the MCPProxy maintainers.*
*Validation: 22 October 2026, MCPProxy v0.71.1, Claude Code 2.1.307 and Codex CLI 0.159.2 on macOS. With the Context7 resolver disabled in an isolated proxy, real sessions in both clients received `TOOL_BLOCKED` and preflight reported `tool_blocked_by_user` (exit `11`). After it was re-enabled, both clients retried successfully and Activity recorded the upstream calls. Other diagnostic paths were checked with isolated proxy and protocol tests, not a real client session for each path. Maintained by the MCPProxy maintainers.*
95 changes: 95 additions & 0 deletions docs/guides/discover-tools-on-demand.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: Keep a growing tool catalog out of initial context
sidebar_label: Discover tools on demand
description: Compare direct and on-demand MCP tool exposure, then prove the agent still completes a real task.
---

# Keep a growing tool catalog out of initial context

When an agent connects to many MCP servers, decide whether it should receive every upstream definition at connection time or discover a relevant tool when needed. This guide uses MCPProxy's two dedicated endpoints to compare both routes on **your** catalog. You are done when a fresh client session finds and calls the intended tool through discovery, and you have recorded the initial `tools/list` size for each route.

## Before you start

Use **MCPProxy v0.71.1 or later**, one running instance, and at least one connected, approved upstream tool you can safely call. Install [uv](https://docs.astral.sh/uv/) for the optional measurement probe in step 2. Identify the tool's exact `server:tool` name and a harmless test request. Both comparisons must use the same proxy, client access scope, and upstream state. If you use a custom data directory, give the CLI the same `--config` and `--data-dir` options as the daemon.

```bash
mcpproxy status
mcpproxy tools list
mcpproxy tools preflight SERVER:TOOL
```

Replace `SERVER:TOOL` with your tool's real ID. Preflight should say `ready`; it checks local availability, not the result of an upstream call. If a tool is held or unavailable, [diagnose that first](/guides/diagnose-unavailable-tool).

## 1. Compare the two client endpoints

In **Clients → Endpoint & mode**, find your proxy's local base URL. Use its dedicated endpoints in two fresh client sessions:

| Endpoint | What a client initially sees | Call pattern |
| --- | --- | --- |
| `/mcp/call` | MCPProxy routing and management tools, including `retrieve_tools`; upstream definitions are requested later | Search with `retrieve_tools`, then use the returned `call_with` tool and exact `server:tool` ID |
| `/mcp/all` | Upstream definitions from connected, non-quarantined servers as direct `server__tool` names, alongside MCPProxy tools | Call the direct name; an access gate can still refuse it |

The configured `/mcp` endpoint follows your instance's `routing_mode`; the two dedicated endpoints work regardless of that setting. Keep the comparison to the same client identity/profile so access filtering is comparable. Direct mode can be convenient for a small known catalog; discovery adds a search step and depends on useful tool descriptions. See [Routing Modes](/features/routing-modes) for the full behavior.

## 2. Measure the initial tool list

Set `MCPPROXY_BASE` to the base URL shown by your local instance, **without** `/mcp`. This protocol-only probe uses Python's standard library and prints the number of listed tools, the JSON response size in bytes, and the sum of serialized `inputSchema` bytes. It does not call an upstream tool. If your local `/mcp` endpoint requires authentication, provide your operator key through `MCPPROXY_API_KEY` in the environment without pasting it into the script or a shared transcript.

```bash
export MCPPROXY_BASE=http://127.0.0.1:YOUR_PORT
uv run --no-project python - <<'PY'
import json, os, urllib.request

base = os.environ['MCPPROXY_BASE'].rstrip('/')
key = os.environ.get('MCPPROXY_API_KEY')
for path in ('/mcp/call', '/mcp/all'):
session = None
def request(number, method, params):
global session
headers = {'Content-Type': 'application/json',
'Accept': 'application/json, text/event-stream',
'MCP-Protocol-Version': '2025-03-26'}
if key: headers['X-API-Key'] = key
if session: headers['Mcp-Session-Id'] = session
body = json.dumps({'jsonrpc': '2.0', 'id': number,
'method': method, 'params': params},
separators=(',', ':')).encode()
with urllib.request.urlopen(urllib.request.Request(
base + path, data=body, headers=headers), timeout=20) as r:
session = r.headers.get('Mcp-Session-Id', session)
raw = r.read()
return json.loads(raw), len(raw)
request(1, 'initialize', {'protocolVersion': '2025-03-26',
'capabilities': {}, 'clientInfo': {'name': 'catalog-check', 'version': '1'}})
result, payload_bytes = request(2, 'tools/list', {})
tools = result['result']['tools']
schema_bytes = sum(len(json.dumps(t.get('inputSchema', {}),
separators=(',', ':')).encode()) for t in tools)
print(f'{path}: {len(tools)} tools; {payload_bytes} response bytes; '
f'{schema_bytes} inputSchema bytes')
PY
```

**Expected:** `/mcp/call` has no individual upstream entries; `/mcp/all` includes upstream entries from the non-quarantined catalog. A listed direct tool can still fail an approval or policy gate when called; check real task success separately. The counts and byte totals depend on your configuration, access policy and release. These are **transport JSON bytes**, not model tokens, billed cost, or a prediction of whole-task context use. MCPProxy's own built-in tool schemas also contribute to both totals; the sums need not move in the same direction. A client may transform or cache definitions before sending them to a model. An operator-key probe may also see more than a restricted client.

## 3. Prove discovery completes the task

In a fresh session connected to `/mcp/call`, ask your agent:

> Use MCPProxy `retrieve_tools` to find `SERVER:TOOL` for this task: `YOUR HARMLESS TASK`. Use the returned exact name, current schema and `call_with` route to make one real call. Report the actual result and any tool error. Do not use a shell or web search instead.

**Expected:** the transcript shows `retrieve_tools`, then the matching `call_tool_read`, `call_tool_write`, or `call_tool_destructive` call, followed by a real upstream response. Search results may include multiple candidates; a precise query and `limit` narrow the response. If you use compact retrieval (`detail: "compact"`), fetch the full definition with `describe_tool` before supplying unfamiliar arguments. See the [MCP discovery response contract](/api/rest-api#mcp-tool-surface-compact-responses-and-describe_tool-spec-085).

Run the same harmless task in a fresh session connected to `/mcp/all`. That transcript should call `server__tool` directly. Compare whether **both actually succeed**, plus any extra search and definition requests. A smaller initial list is not a win if the agent fails to find or correctly call the tool.

## 4. Check the recorded call

```bash
mcpproxy activity list --server SERVER --tool TOOL --type tool_call --from=-15m
```

Match the actual arguments, result and session to each client run. If discovery returns no match, try the server name and a short verb from the tool description; confirm it is approved and visible to that client's profile. If a result appears but a call fails, inspect its current schema and the Activity error. Use [Find out why an agent cannot use a tool](/guides/diagnose-unavailable-tool) for connection, review, policy and upstream failures.

For a production choice, repeat the comparison with several representative tasks and your usual client. Initial `tools/list` bytes, retrieval response bytes, task success and client behavior are separate measurements. There is no universal token, latency or cost saving from switching modes.

*Validation: 22 October 2026, MCPProxy v0.71.1 on macOS. Two protocol-only local upstreams each defined 24 tools; one allowed only its echo tool. The probe saw 14 tools / 37,419 JSON bytes on `/mcp/call` and 49 tools / 40,380 bytes on `/mcp/all`; their `inputSchema` sums were 22,289 and 3,900 bytes respectively. Compact one-result retrieval was 1,650 bytes. Both routing paths completed an echo call after readiness. These are fixture measurements, not a benchmark for other catalogs or client model context. Maintained by the MCPProxy maintainers.*
4 changes: 3 additions & 1 deletion docs/guides/index.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Guides
slug: /guides
description: Complete a task with MCPProxy, from sharing one MCP setup across AI clients to diagnosing an unavailable tool.
description: "Complete MCPProxy tasks: share one setup across clients, diagnose unavailable tools, discover tools on demand, and review tool definitions before use."
---

# What do you want to do?
Expand All @@ -13,6 +13,8 @@ New to MCPProxy? [Install it first](/getting-started/installation), then follow
| --- | --- |
| [Reuse one MCP setup in two AI clients](/guides/two-clients-one-setup) | Claude Code and Codex using the same upstream, with a successful call from each recorded in Activity. |
| [Find out why an agent cannot use a tool](/guides/diagnose-unavailable-tool) | A diagnosed connection, approval, access or call failure, followed by a verified retry. |
| [Discover tools on demand](/guides/discover-tools-on-demand) | A measured comparison of initial tool definitions and a successful call through discovery. |
| [Review a tool before use](/guides/review-tool-before-use) | A deliberate approval decision for a new server and a changed tool definition. |

## Choose the right reference

Expand Down
83 changes: 83 additions & 0 deletions docs/guides/review-tool-before-use.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
---
title: Review a tool before exposing it to your agent
sidebar_label: Review a tool before use
description: Inspect and approve a first server deliberately, then handle a changed tool definition without bypassing the review hold.
---

# Review a tool before exposing it to your agent

An upstream tool description or schema is supplied by the server that runs the tool. Review it before allowing an agent to call it, and review a later captured contract change before accepting it. This guide covers both the first approval of a quarantined server and a changed tool on an already trusted server. You are done when only your chosen tool is callable and a real call succeeds.

## Before you start

Use **MCPProxy v0.71.1 or later** and an upstream whose source and requested access you can evaluate. Run operator commands on the machine hosting the proxy. The examples use `notes` and its `read_note` tool; replace both names with your exact server and tool. If the daemon uses a custom config or data directory, pass its `--config` and `--data-dir` options to every CLI command.

The default `manual` trust mode holds a new server for review and holds later substantive changes to a captured tool contract. Equivalent input-schema key order and `required` order do not count as a change; older approval records have [one-time migration exceptions](/features/security-quarantine#what-quarantine-does-and-does-not-cover). The guard cannot detect an implementation or result change when the definition stays the same. `scan` can admit a new server or new tool after a clean offline scan, but **holds a changed captured contract**. `auto`, global `quarantine_enabled: false`, and the legacy `auto_approve_tool_changes: true` option can remove these holds. Confirm the effective [trust mode](/features/security-quarantine#trust-modes-auto--scan--manual) before relying on a review queue.

## 1. Capture the first review

Add a new server with your real transport details, using `manual` trust. For example, an HTTP upstream:

```bash
mcpproxy upstream add notes https://YOUR-SERVER.example/mcp --trust-mode manual
mcpproxy review list
mcpproxy review fetch notes
mcpproxy review show notes --full
```

**Expected:** `notes` is quarantined. `review fetch` captures its definitions without admitting it. If an existing `notes` entry already exists, inspect that entry instead of adding a duplicate. If capture fails, check the server URL, authentication and `mcpproxy upstream logs notes`; do not approve unseen tools.

Read the source URL or command, every tool you plan to allow, descriptions, input and output schemas, and safety hints. A read-only annotation is the upstream's claim; verify the operation and where its data goes. Treat instructions inside a tool description as untrusted content, especially requests to change the agent's priorities, reveal secrets or send data elsewhere.

## 2. Scan, decide, and approve only the intended tool

```bash
mcpproxy security scan notes
mcpproxy security report notes
mcpproxy review show notes --full
```

The offline scan supplies findings and a verdict for the captured definitions. Check whether the review says the scan **covers** what is currently shown. A missing, failed, dangerous or out-of-date scan needs investigation or a fresh scan; a clean scan is evidence, not proof that a tool is safe or suitable for your task.

After accepting `read_note` and its access, run:

```bash
mcpproxy review approve notes --tools read_note
mcpproxy tools preflight notes:read_note --wait 10s
```

Read the approval prompt and the resulting counts. On a quarantined server, `--tools read_note` allows that tool and **blocks the others**; selecting a tool does not imply approval of the full catalog. Blocked tools cannot execute. In v0.71.1, the direct `/mcp/all` list can still include a blocked sibling's definition after server approval; use on-demand discovery if you also need to keep unselected definitions out of the initial client list. Preflight should report `ready` (exit `0`) after startup. It reads local state and does not make the upstream call. If the review changed during approval, MCPProxy refuses the stale decision; fetch/show the current definitions and decide again. See [Review commands](/cli/review-commands) for saved, fingerprint-bound reviews and the Web UI equivalent.

## 3. Review a later tool change

When a trusted server changes a tool's description, input/output schema or safety hints, it may appear in the Review queue as `changed`. Do not approve from its name alone:

```bash
mcpproxy review list
mcpproxy review show notes --full
mcpproxy tools preflight notes:read_note
mcpproxy security report notes
```

**Expected for a held change:** `review show` displays the previous and current definition, including the diff; preflight reports `tool_changed` (usually exit `11`). Check what the new arguments permit, whether the operation still matches the name and annotations, and whether the scan covers the **current** definition. If the report is stale, run `mcpproxy security rescan notes`, then inspect it again. A clean result does **not** release a changed contract under `manual` or `scan` trust.

If you accept the new contract, approve that one tool and verify it:

```bash
mcpproxy review approve notes --tools read_note
mcpproxy tools preflight notes:read_note --wait 10s
```

If you do not accept it, leave it held or use `mcpproxy review reject notes --tools read_note` to acknowledge and block it. Blocking disables the tool; later enabling it is a separate decision. Avoid `--force`, turning off quarantine or switching to `auto` to resolve a review hold.

## 4. Prove the agent's access and call

In your intended client, start a fresh session and ask it to find and call `notes:read_note` with harmless arguments. In `retrieve_tools` mode, it should search first and use the returned `call_with` route; in direct mode it should call `notes__read_note`. Then inspect:

```bash
mcpproxy activity list --server notes --tool read_note --type tool_call --from=-15m
```

**Completion check:** the chosen tool is visible to that client, the real call succeeds with the expected arguments, and Activity records it. If operator preflight says `ready` but the client cannot see it, check that client's profile and credential. If the call fails, inspect its Activity result and follow [Find out why an agent cannot use a tool](/guides/diagnose-unavailable-tool). A scan result, approval message or preflight result alone does not prove the agent completed the task.

*Validation: 22 October 2026, MCPProxy v0.71.1 on macOS. A controlled local MCP fixture was quarantined, its 24 definitions captured and scanned, and only one tool approved. After that tool's benign description changed, `review show` displayed the diff and preflight returned `tool_changed`. A fresh scan reported 0 findings and risk 0 while the tool remained held. The fixture was a protocol test, not an external client UI test. Maintained by the MCPProxy maintainers.*
Loading
Loading