docs: ALLOWED_ORIGINS recipe for a *.localhost proxy

[cliffhall]

Closes #2289

Running the Inspector behind a reverse proxy on a *.localhost name — inspector.localhost, alongside my-api.localhost / my-app.localhost — works today, but only with ALLOWED_ORIGINS set, and nothing in the docs said so or showed the shape. Raised by the reporter of #1944, whose whole service cluster uses those names.

Documented rather than changing the default: #2282 has the reasoning, but briefly, ~1,100 lines of security-sensitive origin and CSP code across four layers was a poor trade for removing one environment variable from a setup that already works.

Three things the recipe has to carry

Each was learned the expensive way while investigating #1944, and each is the kind of thing that turns a five-minute fix into an afternoon:

1. ALLOWED_ORIGINS replaces the default list, it does not merge. An entry of only http://inspector.localhost silently breaks browsing at localhost:6274. The loopback trio has to be listed too.
2. The failure is confusing rather than obvious. A same-origin GET carries no Origin header, so it never reaches the guard — the page loads fine, and only the POSTs that add or connect a server are rejected with a 403. That reads as a connection problem, not a configuration one, which is why it is worth documenting rather than leaving to be rediscovered.
3. Only the browser resolves *.localhost for free. Chrome and Firefox map those names to loopback per RFC 6761 §6.3; the OS resolver on macOS does not, and Safari does not at all. Fine for reaching the Inspector; an MCP server on such a host is dialled by the Node backend and still needs /etc/hosts or dnsmasq — and with OAuth is refused by the SDK regardless (typescript-sdk#2591).

Also notes that the MCP Apps sandbox frame-ancestors derives from the same list, so one entry covers the Apps tab.

Testing

Docs only, no behavior change. npm run format + npm run local:gate → EXIT=0, zero failures.

[Copilot]

🟡 Changes recommended

The troubleshooting text incorrectly implies that only POST requests fail, while PUT and DELETE operations are also rejected.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documents how to configure ALLOWED_ORIGINS when proxying the web Inspector through a *.localhost hostname.

Changes:

• Adds a complete proxy-origin configuration example.
• Documents loopback, MCP Apps, browser-resolution, and OAuth caveats.

File summaries

File	Description
clients/web/README.md	Adds the *.localhost reverse-proxy recipe and troubleshooting guidance.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[cliffhall]

Review round 1 — addressed

One finding, correct. My wording implied only the add/connect POSTs are rejected; PUT (save, reorder) and DELETE (remove) carry Origin too and fail identically, since the middleware is method-agnostic and browsers attach Origin to everything that is not GET/HEAD.

Now "every state-changing request", with the POSTs kept as the visible examples. For a troubleshooting note the precision is the whole value — someone whose save silently fails needs to recognise themselves in the text.

npm run local:gate → EXIT=0, zero failures.

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the implementation and fulfills the linked issue’s requirements.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Balanced