Allow configuring the advertised MCP Apps sandbox URL

[eitansuez]

Allow configuring the advertised MCP Apps sandbox URL (e.g. MCP_SANDBOX_FULL_ADDRESS)

Summary

Please add a way to override the public MCP Apps sandbox URL returned by GET /api/config as sandboxUrl, independent of the process bind address.

Today the sandbox listen URL is built in clients/web/server/sandbox-controller.ts roughly as:

sandboxUrl = `http://${urlHost}:${actualPort}/sandbox`;

When the server binds 0.0.0.0, urlHost is forced to localhost. There is MCP_SANDBOX_PORT for the port, but no env/config for scheme + hostname (unlike v1’s MCP_PROXY_FULL_ADDRESS for the proxy).

Why this matters

In remote / container / lab setups the browser does not share the Inspector process’s localhost:

• UI is reached at a public hostname, e.g. https://inspector.example.com/
• Sandbox is (or can be) routed separately, e.g. https://inspector-sandbox.example.com/sandbox
• /api/config still advertises http://localhost:6275/sandbox
• “Open App” points the iframe at the browser’s localhost → connection refused / mixed content on HTTPS

Routing port 6275 and setting ALLOWED_ORIGINS is not enough; the advertised sandboxUrl must be a URL the browser can actually open.

This also affects Docker, k8s ingress, and any reverse-proxy hostname split between UI and sandbox.

Proposed solution

Something parallel to v1 MCP_PROXY_FULL_ADDRESS, for example:

MCP_SANDBOX_FULL_ADDRESS=https://inspector-sandbox.example.com/sandbox

Behavior:

1. If set, use it as sandboxUrl in GET /api/config (and banner).
2. If unset, keep current bind-derived http://<host>:<port>/sandbox behavior.
3. Document that the process must still listen on MCP_SANDBOX_PORT (or equivalent) and that the public URL must be routed to that listener.
4. ALLOWED_ORIGINS remains responsible for UI origin / frame-ancestors (orthogonal).

Alternatives considered

• SSH/port-forward both 6274 and 6275 so the browser uses localhost (works for dev; not for public Instruqt/k8s hostnames).
• Rewrite /api/config at the gateway (works as a lab hack; shouldn’t be required).
• Patch sandbox-controller.ts locally.

Related

• Docs already note forwarding both UI and sandbox ports for remote App review.
• #1276 is related remote/embed friction (referrer allowlist), but not the advertised URL override.
• v1 precedent: MCP_PROXY_FULL_ADDRESS.

Environment

• @modelcontextprotocol/inspector v2.0.0
• Instruqt / k3d: UI on public HTTPS hostname; sandbox needs a second public hostname → pod :6275

[eitansuez]

Local implementation (lab-verified)

In this branch is an implementation for this issue, which I verified with an instruqt lab that launches an mcp inspector tab connecting to the example mcp server system-monitor-server from the mcp-apps extension.

there were three distinct parts:

1. exposing the environment variable MCP_SANDBOX_FULL_ADDRESS
2. a packaging issue that left out sandbox.html apparently
3. a sort of allow origin issue that prevented loading the page.

My branch

sharing intent + verification rather than a PR.

Behavior before

• /api/config advertised http://localhost:6275/sandbox under 0.0.0.0 bind
• Public hostname / HTTPS UI → Apps iframe unusable

Behavior after

1. MCP_SANDBOX_FULL_ADDRESS — public sandbox URL in /api/config (listen port unchanged; pin with MCP_SANDBOX_PORT)
2. Ship clients/web/static in the npm packlist (otherwise Docker/npm ENOENT on /sandbox)
3. Inject ALLOWED_ORIGINS into sandbox_proxy.html referrer check (was localhost-only)

Env that worked in lab

• MCP_SANDBOX_PORT=6275
• MCP_SANDBOX_FULL_ADDRESS=https://<sandbox-host>/sandbox # path required
• ALLOWED_ORIGINS=https://<inspector-ui-host> # origin only, no path

Verification

• sandbox-controller integration tests
• Instruqt: Open App on “Get System Info” works end-to-end

[cliffhall]

Triage: Priority = Low

Scored 5/16 with the priority rubric added to AGENTS.md in #1891, as part of the backlog triage in #1872. Added to project board #28 with Status Incoming — meaning filed and scored but not yet approved for work. A maintainer decides whether it moves to Todo.

Axis	Score	Reasoning
Severity / impact	2/5	A configurability gap. The sandbox works; its advertised URL just can't be pointed elsewhere.
Urgency / staleness	3/5	Wanted for non-loopback deployments, no deadline.
Signal bonuses	+0	none apply
Total	5	Lands in the Low band (5 or below).

Related issues. One connected issue:

• Sanbox not loaded: ENOENT: no such file or directory, open ..../@modelcontextprotocol/inspector/clients/web/static/sandbox_proxy.html #1859 — the sandbox-path failure — same subsystem, and a fix there may inform the shape of this

Scores are a starting point, not a verdict — the rubric is meant to be overruled when it's plainly wrong, provided the reason is written down.