Document proxy mode and proxy port fields by samuv · Pull Request #852 · stacklok/docs-website

samuv · 2026-05-08T13:09:12Z

Description

Closes #772.

Summary

Document Proxy mode (stdio + non-Bearer-Token only; SSE / Streamable HTTP) and Proxy port (optional HTTP proxy listener) across the registry Local MCP and Remote MCP tabs and both Custom local MCP flows in run-mcp-servers.mdx.
Document Proxy port under Custom remote MCP and explicitly note that Proxy mode is not shown for remote transports.
Clarify that Target port is the container port and Proxy port is the HTTP proxy ToolHive listens on, so the two are no longer conflated.
Verified UI strings against stacklok/toolhive-studio at tag v0.30.0.

Test plan

npm run build passes
Verify the new bullets render in both tab variants and the renumbered Custom remote MCP list reads correctly

Type of change

Documentation update

Related issues/PRs

Closes #772

Submitter checklist

Content and formatting

I have reviewed the content for technical accuracy
I have reviewed the content for spelling, grammar, and style

Made with Cursor

Cover the Proxy mode and Proxy port form fields across the registry, custom Docker image, custom source package, and custom remote MCP server flows so readers can distinguish the HTTP proxy port from the container target port. Refs #772 Co-authored-by: Cursor <cursoragent@cursor.com>

vercel · 2026-05-08T13:09:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	May 8, 2026 4:15pm

Copilot

Pull request overview

Updates the ToolHive UI guide to document the Proxy mode and Proxy port fields in MCP server install/configuration flows, clarifying how ToolHive’s HTTP proxy relates to container target ports and remote transports.

Changes:

Added documentation for Proxy mode (conditional for stdio) and Proxy port (optional HTTP proxy listener) in the registry Local MCP flow.
Added documentation for Proxy port in the registry Remote MCP flow and the Custom remote MCP flow, noting Proxy mode is not shown for remote transports.
Clarified target port vs proxy port in both Custom local MCP flows (Docker image and source package).

danbarr · 2026-05-08T14:04:54Z

+   configured for bearer-token authentication. For `sse` and `streamable-http`
+   transports, the MCP server already speaks HTTP, so no proxy mode selection is
+   needed.


Disagree with Copilot here, "bearer token" isn't generally hyphenated, but it shouldn't be capitalized unless specifically referring to a UI element to match.

Suggested change

configured for bearer-token authentication. For `sse` and `streamable-http`

transports, the MCP server already speaks HTTP, so no proxy mode selection is

needed.

configured for bearer token authentication. For `sse` and `streamable-http`

transports, the MCP server already speaks HTTP, so no proxy mode selection is

needed.

Agreed. Reverted to lowercase "bearer token authentication" here at 33b9ec9, and kept bold Bearer Token only when referring to the picker option label.

danbarr · 2026-05-08T14:05:23Z

+   The proxy transport mode that clients should use to connect to this server.
+   Choose **SSE** (`sse`) or **Streamable HTTP** (`streamable-http`). This
+   option appears only when the **transport protocol** is `stdio` and you're not
+   using bearer-token authentication.


Same as above, my suggestion would be "bearer token"

Suggested change

using bearer-token authentication.

using bearer token authentication.

Same lowercase fix applied to this Custom Docker bullet at 33b9ec9.

danbarr · 2026-05-08T14:05:27Z

+   The proxy transport mode that clients should use to connect to this server.
+   Choose **SSE** (`sse`) or **Streamable HTTP** (`streamable-http`). This
+   option appears only when the **transport protocol** is `stdio` and you're not
+   using bearer-token authentication.


Same as above, my suggestion would be "bearer token"

Suggested change

using bearer-token authentication.

using bearer token authentication.

Same lowercase fix applied to the Custom source bullet at 33b9ec9.

danbarr

Nice tightening of the target-port / proxy-port distinction. A few editorial points beyond the inline comments:

Primary issue

Default value for Proxy mode is missing

The new Proxy mode bullets describe the choice but don't say which option is the default. The CLI guide documents this at docs/toolhive/guides-cli/run-mcp-servers.mdx:363-364: "As of ToolHive CLI version 0.6.0, the default proxy mode for stdio MCP servers is streamable-http." A UI reader looking at the form needs the same information; omitting it forces them to guess or experiment.

Ask: State the default in the Proxy mode bullets, e.g., "Streamable HTTP is the default."

Secondary issues

Issue	Recommendation
Same condition phrased two ways: "the MCP server uses the `stdio` transport" (line 110) vs. "the transport protocol is `stdio`" (lines 311, 385)	Unify on the transport protocol wording, since it points readers to the actual form field.
Target-port-vs-proxy-port distinction phrased two ways in the same PR: "distinct from" (line 114) vs. "separate from" (lines 315, 389)	Pick one.
New trailing sentence on the existing Target port bullet ("Selecting `stdio` hides this field, since `stdio` servers don't expose a port from the container", lines 304-305 and 378-379) duplicates the bullet's existing parenthetical "(SSE or Streamable HTTP transports only)"	Drop the trailing sentence; the condition is already conveyed.

danbarr · 2026-05-08T14:07:18Z

+   Port for the HTTP proxy to listen on. If not specified, ToolHive will
+   automatically assign a random port. This is the port that AI clients connect


Fix passive voice:

Suggested change

Port for the HTTP proxy to listen on. If not specified, ToolHive will

automatically assign a random port. This is the port that AI clients connect

Port for the HTTP proxy to listen on. If not specified, ToolHive

automatically assigns a random port. This is the port that AI clients connect

Switched this Proxy port description to active voice at 33b9ec9: "ToolHive automatically assigns a random port".

danbarr · 2026-05-08T14:08:27Z

+   Port for the HTTP proxy to listen on. If not specified, ToolHive will
+   automatically assign a random port. This is the port that AI clients connect


Fix passive voice:

Suggested change

Port for the HTTP proxy to listen on. If not specified, ToolHive will

automatically assign a random port. This is the port that AI clients connect

Port for the HTTP proxy to listen on. If not specified, ToolHive

automatically assigns a random port. This is the port that AI clients connect

Same active-voice fix applied on the Custom Docker Proxy port bullet at 33b9ec9.

danbarr · 2026-05-08T14:08:49Z

+   Port for the HTTP proxy to listen on. If not specified, ToolHive will
+   automatically assign a random port. **Proxy mode** is not shown for remote


Fix passive voice:

Suggested change

Port for the HTTP proxy to listen on. If not specified, ToolHive will

automatically assign a random port. **Proxy mode** is not shown for remote

Port for the HTTP proxy to listen on. If not specified, ToolHive

automatically assigns a random port. **Proxy mode** is not shown for remote

Active voice applied on this bullet at 33b9ec9, kept the "Proxy mode is not shown for remote" note as suggested.

danbarr · 2026-05-08T14:09:29Z

+   Port for the HTTP proxy to listen on. If not specified, ToolHive will
+   automatically assign a random port. This is the port that AI clients connect


Fix passive voice:

Suggested change

Port for the HTTP proxy to listen on. If not specified, ToolHive will

automatically assign a random port. This is the port that AI clients connect

Port for the HTTP proxy to listen on. If not specified, ToolHive

automatically assigns a random port. This is the port that AI clients connect

Same active-voice fix applied to the Custom source Proxy port bullet at 33b9ec9.

danbarr · 2026-05-08T14:10:23Z

+   Port for the HTTP proxy to listen on. If not specified, ToolHive will
+   automatically assign a random port. **Proxy mode** is not shown for remote


Fix passive voice:

Suggested change

Port for the HTTP proxy to listen on. If not specified, ToolHive will

automatically assign a random port. **Proxy mode** is not shown for remote

Port for the HTTP proxy to listen on. If not specified, ToolHive

automatically assigns a random port. **Proxy mode** is not shown for remote

Active voice applied here as well at 33b9ec9, with the "Proxy mode is not shown for remote" sentence preserved.

Address Copilot feedback on #852: align with the UI label "Bearer Token" instead of "bearer-token". Co-authored-by: Cursor <cursoragent@cursor.com>

Address danbarr's CHANGES_REQUESTED review on #852: state the default Streamable HTTP, lowercase "bearer token", switch to active voice for port assignment, standardize on "distinct from", drop redundant target-port copy, and align UI string formatting. Co-authored-by: Cursor <cursoragent@cursor.com>

samuv · 2026-05-08T16:39:02Z

Thanks for the review. Pushed updates as 33b9ec9.

Added "Streamable HTTP is the default." to every conditional Proxy mode bullet (registry, Custom Docker, Custom source).
Unified the transport-condition wording on "the transport protocol is stdio" everywhere, replacing the older "uses the stdio transport" phrasing.
Standardized on "distinct from" when contrasting Proxy port with target port across all three flows.
Dropped the redundant "Selecting stdio hides this field..." sentence from the Target port bullets in Custom Docker and Custom source, since the existing parenthetical already conveys the condition.
Reverted the hyphenated "bearer-token" and Copilot's capitalized "Bearer Token authentication" to lowercase "bearer token authentication" in prose. Bold Bearer Token stays only when referring to the picker option label.
Switched Proxy port descriptions to active voice ("ToolHive automatically assigns a random port") wherever passive voice had crept in.
Applied the bold-for-short-labels / blockquote-for-tooltip-copy rule across the proxy-mode area.

danbarr

All feedback addressed: default value added ("Streamable HTTP is the default."), conditional phrasing unified across the three sibling sections, "distinct from" used consistently, trailing redundant sentence on Target port removed, inline comments resolved (active voice, lowercase "bearer token authentication"). Thanks!

Copilot AI review requested due to automatic review settings May 8, 2026 13:09

vercel Bot deployed to Preview May 8, 2026 13:09 View deployment

Copilot started reviewing on behalf of samuv May 8, 2026 13:09 View session

samuv self-assigned this May 8, 2026

Copilot AI reviewed May 8, 2026

View reviewed changes

danbarr requested changes May 8, 2026

View reviewed changes

samuv and others added 2 commits May 8, 2026 16:57

Match Bearer Token UI label in proxy mode docs

a3d39bc

Address Copilot feedback on #852: align with the UI label "Bearer Token" instead of "bearer-token". Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview May 8, 2026 16:15 View deployment

danbarr approved these changes May 8, 2026

View reviewed changes

danbarr merged commit 5ed132c into main May 8, 2026
20 checks passed

danbarr deleted the docs-772-proxy-mode-port branch May 8, 2026 19:48

	using bearer-token authentication.
	using bearer token authentication.

		Port for the HTTP proxy to listen on. If not specified, ToolHive will
		automatically assign a random port. This is the port that AI clients connect

		Port for the HTTP proxy to listen on. If not specified, ToolHive will
		automatically assign a random port. Proxy mode is not shown for remote

Conversation

samuv commented May 8, 2026

Description

Summary

Test plan

Type of change

Related issues/PRs

Submitter checklist

Content and formatting

Uh oh!

vercel Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

danbarr May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danbarr May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danbarr May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danbarr left a comment

Choose a reason for hiding this comment

Primary issue

Default value for Proxy mode is missing

Secondary issues

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samuv commented May 8, 2026

Uh oh!

danbarr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented May 8, 2026 •

edited

Loading

danbarr May 8, 2026 •

edited

Loading

danbarr May 8, 2026 •

edited

Loading

danbarr May 8, 2026 •

edited

Loading