Skip to content

fix: say how Gemini CLI actually picks a transport for a url entry #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sepehr-safari merged 1 commit into from
Sep 23, 2026
Merged

fix: say how Gemini CLI actually picks a transport for a url entry #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
25 changes: 16 additions & 9 deletions src/pages/guides/gemini-cli.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,10 +80,14 @@ const guide = findGuide('gemini-cli');
<code>agent-chaperone wrap ~/.gemini/settings.json</code> can make the command change, but not
the <code>env</code> 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. Leave remote servers out of it: in Gemini CLI a <code>url</code> entry
means the older SSE transport and <code>httpUrl</code> means Streamable HTTP, and{' '}
<code>wrap</code> skips <code>httpUrl</code> entries and would treat a <code>url</code> entry
as Streamable HTTP.
and left untouched. A server Gemini CLI reaches by <code>url</code> is wrapped too, from
0.3.2. Gemini CLI reaches a <code>url</code> entry over Streamable HTTP, the transport the
proxy uses too, unless the entry says <code>"type": "sse"</code>, and a{' '}
<code>"type": "http"</code> becomes <code>stdio</code> once the entry runs a command. An entry
that declares SSE, or carries its own <code>headers</code>, is left alone and the output says
why. So is one written with <code>httpUrl</code>, the older spelling Gemini CLI has deprecated
in favour of <code>url</code> with <code>"type": "http"</code>; make that change and run{' '}
<code>wrap</code> again.
</p>
</section>

Expand Down Expand Up @@ -147,11 +151,14 @@ const guide = findGuide('gemini-cli');
those <a href={`${REPO}/issues/78`}>does not exist yet</a>.
</li>
<li>
<b>A server Gemini CLI reaches by URL.</b> Put an <code>httpUrl</code> server behind the
proxy by hand, as <a href="/guides/mcp-security#wrap">the MCP guide</a> shows, with the URL
after <code>--</code>, and pass any token it needs with <code>--header-env</code>: headers
written in the Gemini CLI entry never reach the proxy. A <code>url</code> server speaks SSE,
and the proxy reaches a URL over Streamable HTTP only.
<b>A server that authenticates with headers.</b> Headers written in the Gemini CLI entry
never reach the proxy, which is why <code>wrap</code> leaves such an entry alone. Put it
behind the proxy by hand, as <a href="/guides/mcp-security#wrap">the MCP guide</a> shows,
and pass the token with <code>--header-env</code>.
</li>
<li>
<b>A server that speaks only SSE.</b> The proxy reaches a URL over Streamable HTTP and
nothing else, so an entry with <code>"type": "sse"</code> stays as it is.
</li>
<li>
<b>What a server does rather than what the call says.</b> This is not a sandbox. It reads
Expand Down
Loading