From 9e560ae55b28196de2f3aca5095153343e22aa78 Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Wed, 23 Sep 2026 16:29:13 +0300 Subject: [PATCH] fix: describe wrap as of 0.3.2 in the client guides 0.3.2 changes what `wrap` does with a remote entry: a declared `type: "http"` becomes `stdio` once the entry runs the proxy, and an entry carrying its own headers or auth, or declaring the older SSE transport, is skipped with the reason. The VS Code and Cursor guides said to keep remote servers away from `wrap` altogether, which was right for 0.3.1 and is now more caution than a reader needs. They now say what it does with each kind of entry, and what is left for a hand edit with `--header-env`. The Gemini CLI guide keeps its advice to wrap remote servers by hand, with the reason now stated: Gemini CLI spells Streamable HTTP as `httpUrl`, which `wrap` skips, and uses `url` for SSE, which the proxy cannot reach. The site also said it describes 0.3.0, two releases behind npm, and now says 0.3.2. --- src/data/benchmark.ts | 2 +- src/pages/guides/cursor.astro | 17 ++++++++++------- src/pages/guides/gemini-cli.astro | 15 +++++++++------ src/pages/guides/vscode.astro | 25 ++++++++++++++++--------- 4 files changed, 36 insertions(+), 23 deletions(-) diff --git a/src/data/benchmark.ts b/src/data/benchmark.ts index 699be6b..5d0110d 100644 --- a/src/data/benchmark.ts +++ b/src/data/benchmark.ts @@ -24,7 +24,7 @@ export const RUN = { * start claiming to come from a run nobody made. This one says what a reader * would install today. They were the same version once and are not any more. */ -export const CURRENT_VERSION = '0.3.0'; +export const CURRENT_VERSION = '0.3.2'; /** The thresholds the package actually ships with, from src/policy/schema.ts. */ export const SHIPPED = { diff --git a/src/pages/guides/cursor.astro b/src/pages/guides/cursor.astro index 75d61de..8b3905b 100644 --- a/src/pages/guides/cursor.astro +++ b/src/pages/guides/cursor.astro @@ -152,13 +152,16 @@ agent-chaperone wrap ~/.cursor/mcp.json --write which does not exist yet.
  • - - A remote server wrapped by wrap. - {' '} - Wrap a server Cursor reaches by URL by hand instead, as{' '} - the MCP guide shows, and pass any token it needs - with --header-env. Headers written in the Cursor entry stay with Cursor and - never reach the proxy. + A server that authenticates with headers. Headers written in the Cursor entry stay + with Cursor and never reach the proxy, which is why wrap, from 0.3.2, leaves + such an entry alone. Put it behind the proxy by hand, as{' '} + the MCP guide shows, and pass the token with{' '} + --header-env. +
    • +
  • + A server that speaks only the older SSE transport. wrap treats a{' '} + url entry as Streamable HTTP, the only transport the proxy reaches a URL over, + so a server that answers over SSE alone will not connect once wrapped.
  • What a server does rather than what the call says. This is not a sandbox. It reads diff --git a/src/pages/guides/gemini-cli.astro b/src/pages/guides/gemini-cli.astro index 78c7e63..d598533 100644 --- a/src/pages/guides/gemini-cli.astro +++ b/src/pages/guides/gemini-cli.astro @@ -80,8 +80,10 @@ const guide = findGuide('gemini-cli'); agent-chaperone wrap ~/.gemini/settings.json can make the command change, but not the env line, which you add afterwards. It reads the file as strict JSON, and Gemini CLI allows comments in its settings, so a file with comments is refused with an error - and left untouched. It also wraps every server in the file, so use it on a file whose servers - all run a local command. + and left untouched. Leave remote servers out of it: in Gemini CLI a url entry + means the older SSE transport and httpUrl means Streamable HTTP, and{' '} + wrap skips httpUrl entries and would treat a url entry + as Streamable HTTP.

    @@ -145,10 +147,11 @@ const guide = findGuide('gemini-cli'); those does not exist yet.
  • - A server Gemini CLI reaches by URL. Put it behind the proxy by hand, as{' '} - the MCP guide shows, and pass any token it needs - with --header-env: headers written in the Gemini CLI entry never reach the - proxy. + A server Gemini CLI reaches by URL. Put an httpUrl server behind the + proxy by hand, as the MCP guide shows, with the URL + after --, and pass any token it needs with --header-env: headers + written in the Gemini CLI entry never reach the proxy. A url server speaks SSE, + and the proxy reaches a URL over Streamable HTTP only.
  • What a server does rather than what the call says. This is not a sandbox. It reads diff --git a/src/pages/guides/vscode.astro b/src/pages/guides/vscode.astro index bfc0f8e..55fd911 100644 --- a/src/pages/guides/vscode.astro +++ b/src/pages/guides/vscode.astro @@ -79,11 +79,13 @@ const guide = findGuide('vscode'); --server names the section of the policy file that applies.

    - agent-chaperone wrap can make the edit, with two limits on VS Code. It reads the - file as strict JSON, and VS Code allows comments in mcp.json, so a file with - comments is refused with an error and left untouched. And it wraps every server in the file, - so use it on a file whose servers all run a local command. Otherwise edit the entry by hand as - above. + agent-chaperone wrap can make the edit. It reads the file as strict JSON, and VS + Code allows comments in mcp.json, so a file with comments is refused with an + error and left untouched; edit that one by hand as above. A server VS Code reaches by URL is + wrapped too, from 0.3.2, with its type changed from http to{' '} + stdio because the entry now runs a command, and --unwrap changes it + back. One that carries its own headers, or declares the older SSE transport, is + left alone and the output says why. 

    agent-chaperone wrap .vscode/mcp.json
 agent-chaperone wrap .vscode/mcp.json --write
    @@ -161,10 +163,15 @@ agent-chaperone wrap .vscode/mcp.json --write an adapter for them does not exist yet.
  • - A server VS Code reaches by URL. Put it behind the proxy by hand, as{' '} - the MCP guide shows, with type set to{' '} - stdio, since the entry now runs a command. Pass any token it needs with{' '} - --header-env: headers written in the VS Code entry never reach the proxy. + A server that authenticates with headers. Headers written in the VS Code entry never + reach the proxy, which is why wrap leaves such an entry alone. Put it behind + the proxy by hand, as the MCP guide shows, with{' '} + type set to stdio, and pass the token with{' '} + --header-env. +
    • +
  • + A server that speaks only the older SSE transport. The proxy reaches a URL over + Streamable HTTP and nothing else.
  • What a server does rather than what the call says. This is not a sandbox. It reads