diff --git a/docs/guides/diagnose-unavailable-tool.md b/docs/guides/diagnose-unavailable-tool.md index 68b979bef..12050dd7e 100644 --- a/docs/guides/diagnose-unavailable-tool.md +++ b/docs/guides/diagnose-unavailable-tool.md @@ -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. | @@ -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 @@ -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.* diff --git a/docs/guides/discover-tools-on-demand.md b/docs/guides/discover-tools-on-demand.md new file mode 100644 index 000000000..930a69f7b --- /dev/null +++ b/docs/guides/discover-tools-on-demand.md @@ -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.* diff --git a/docs/guides/index.md b/docs/guides/index.md index d414d732a..d151cc2b3 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -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? @@ -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 diff --git a/docs/guides/review-tool-before-use.md b/docs/guides/review-tool-before-use.md new file mode 100644 index 000000000..394dfb08c --- /dev/null +++ b/docs/guides/review-tool-before-use.md @@ -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.* diff --git a/docs/guides/two-clients-one-setup.md b/docs/guides/two-clients-one-setup.md index 88445d1a7..d56a94546 100644 --- a/docs/guides/two-clients-one-setup.md +++ b/docs/guides/two-clients-one-setup.md @@ -91,6 +91,8 @@ Approve the client's tool-use prompt if it asks. Repeat the same request in Code 2. The agent uses the returned `call_with` tool (normally `call_tool_read`) to invoke that exact name with `libraryName` and `query`. 3. Context7 returns actual library matches. Their IDs and contents can change; do not compare against a hard-coded ID. +If a client cannot start an authenticated AI session, complete its sign-in first and repeat this step. A successful MCP connection or a direct protocol test cannot stand in for a call made by that client. + In discovery mode, seeing only MCPProxy's small set of routing tools in `/mcp` is normal. The upstream tools appear through retrieval. If the agent chooses another route, use the [agent-instructions snippet](/features/agent-instructions) and repeat the explicit request. ## 5. Verify both calls in Activity @@ -119,4 +121,4 @@ Follow [Find out why an agent cannot use a tool](/guides/diagnose-unavailable-to - Disconnect only the client entry you no longer want with `mcpproxy disconnect claude-code` or `mcpproxy disconnect codex`. See [client credential lifecycle](/features/connect-clients#using-client-credentials) for revocation; removing a config entry and revoking its credential are distinct actions. - To stop using the example upstream while keeping its configuration, run `mcpproxy upstream disable context7`. -*Validation: 22 October 2026, MCPProxy v0.71.1 on macOS. Upstream review, discovery, calls from two independent MCP sessions and Activity were checked against the released daemon. Client connection instructions were checked against Connect's configuration tests and the linked client references; this is not a claim of an end-to-end UI test of every client release. 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. Both real CLIs used separate scratch client credentials to call the same reviewed Context7 resolver through one isolated proxy; Activity recorded a successful upstream call under each client identity. The Connect configuration flows were checked separately; the live CLI runs used temporary client overrides and did not modify the clients' saved configuration. Maintained by the MCPProxy maintainers.* diff --git a/docs/intro.md b/docs/intro.md index ec7498f74..1b06f5777 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -16,10 +16,10 @@ keywords: [mcp, proxy, ai agents, tool discovery, security, docker] ## What is MCPProxy? -MCPProxy is a Go-based application that acts as an intelligent proxy between AI clients (like Cursor, Claude Desktop, VS Code Copilot) and MCP servers. It runs locally on your machine or LAN and provides: +MCPProxy is a Go-based application that acts as an intelligent proxy between AI clients (such as Claude Code, Codex CLI and Cursor) and MCP servers. It runs locally on your machine or LAN and provides: - **Intelligent Tool Discovery** - BM25 search indexes tools across all connected servers, so that, in the default `retrieve_tools` and `code_execution` routing modes, agents load a small set of MCPProxy discovery and execution tools and fetch tool schemas on demand instead of the full upstream catalog (`direct` routing lists upstream tools individually and does not reduce initial context; savings depend on tool count, routing mode and task) -- **Security Quarantine** - Withholds new servers and tools from agents until you review and approve them, and, under the default `manual` trust mode, holds most later changes to an approved tool's definition for review (known exceptions: input-schema-only edits outside `scan` mode, a newly added output schema, and a description added to a tool approved with an empty description; `scan` and `auto` modes admit more). This reduces exposure to Tool Poisoning Attacks (TPA); it is not a guarantee of safety (see [limits](/features/security-quarantine#what-quarantine-does-and-does-not-cover)) +- **Security Quarantine** - Under the default `manual` trust mode, withholds new servers, new tools and substantive changes to approved tool definitions until approval. `scan` can automatically admit clean new servers and tools but holds changed contracts; `auto` skips these holds. This reduces exposure to Tool Poisoning Attacks (TPA), with [normalization, upgrade exceptions and other limits](/features/security-quarantine#what-quarantine-does-and-does-not-cover); it is not a guarantee of safety. - **Containerized MCP Servers** - Run upstream servers in Docker isolation for enhanced security - **Audit & Transparency** - Local activity records of tool calls for inspection and debugging, with configurable retention and a response size cap per record (not a compliance certification) - **Sensitive Data Detection** - Flags potential API keys, credentials and other sensitive data in tool arguments and responses in the activity log. Optional [output sanitisation](/features/output-sanitisation) can redact detected secrets or block critical detections in supported text responses (not in direct routing mode or upstream error results) @@ -32,7 +32,7 @@ Instead of loading all tools from all servers into your AI client's context, MCP ### Security Quarantine -New MCP servers are automatically quarantined until you review and approve them, and their tools are withheld from agents in the meantime. This reduces exposure to Tool Poisoning Attacks, where a malicious server tries to manipulate AI behavior through crafted tool descriptions. A clean scan is not proof of safety, and trust modes other than `manual` admit servers or changes without a human review. +Under the default `manual` trust mode, new MCP servers are quarantined until approval, and their tools are withheld from agents in the meantime. This reduces exposure to Tool Poisoning Attacks, where a malicious server tries to manipulate AI behavior through crafted tool descriptions. A clean scan is not proof of safety, and trust modes other than `manual` admit servers or changes without a human review. ### Docker Isolation @@ -60,17 +60,25 @@ Ready to get started? Follow the [Installation Guide](/getting-started/installat ## Ecosystem -MCPProxy works with any MCP-compatible client and connects to 100+ MCP servers providing 1000+ tools. Popular integrations include: +MCPProxy works with any MCP-compatible client and connects to 100+ MCP servers providing 1000+ tools. Examples of integrations include: -**AI Clients:** -- Cursor +**AI clients in telemetry reports (September 22–October 22, 2026):** + +- Claude Code +- Codex CLI +- OpenCode - Claude Desktop -- VS Code Copilot -- ChatGPT/Codex -- Goose +- Cursor +- VS Code +- Gemini CLI - Windsurf +- Goose +- ZCode + +This anonymous, incomplete snapshot combines configured integrations with self-reported MCP client names, including names seen before the reporting window. **MCP Servers:** + - GitHub - Playwright - Context7 @@ -90,3 +98,5 @@ MCPProxy works with any MCP-compatible client and connects to 100+ MCP servers p - [Reuse one MCP setup in two AI clients](/guides/two-clients-one-setup) - [Find out why an agent cannot use a tool](/guides/diagnose-unavailable-tool) +- [Discover tools on demand](/guides/discover-tools-on-demand) +- [Review a tool before use](/guides/review-tool-before-use) diff --git a/website/sidebars.js b/website/sidebars.js index 4dd86bc6d..9ec77ca74 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -34,7 +34,12 @@ const sidebars = { type: 'category', label: 'Guides', link: { type: 'doc', id: 'guides/index' }, - items: ['guides/two-clients-one-setup', 'guides/diagnose-unavailable-tool'], + items: [ + 'guides/two-clients-one-setup', + 'guides/diagnose-unavailable-tool', + 'guides/discover-tools-on-demand', + 'guides/review-tool-before-use', + ], }, { type: 'category',