Engineering notesView as Markdown ↗

The MCP endpoint checks the browser's Origin and never leaks internals

In plain terms

AI assistants connect from their own servers and work as normal. A web page in someone's browser can only talk to Biloh's assistant connection if it is on an approved list. When something goes wrong, the assistant gets a clear message and a reference number, never the inner workings.

Before any other gate, the MCP endpoint checks the Origin header of browser requests against a tunable allow list, as the MCP Streamable HTTP transport requires; server-to-server clients send no Origin and are unaffected. At the same door, a tool that throws or returns database or stack text is answered with a plain, specific error and a reference, and the original is logged under that reference.

At a glance

Who it's for:
AI assistants working in a Biloh business
Tools it uses:
update_setting

Which requests does the Origin check affect?

Only browser requests. The MCP Streamable HTTP transport says a server must validate the Origin header and answer 403 when it is present and not allowed. lib/mcp/origin-policy.ts is the one home for that rule, and app/api/mcp/[transport]/route.ts runs it before any other gate:

  • No Origin header: allowed, and the settings are never read. This is how AI assistants call from their own servers, so a connected assistant is never affected.
  • Origin equal to the request's own host: allowed (a tenant's own page on its own domain).
  • Origin on mcp.origin.allowed_origins: allowed. The default list holds biloh's own hosts, the assistant vendors' web apps and a local MCP Inspector (http://localhost:*).
  • Anything else: 403 origin_not_allowed, with a sentence saying server-to-server clients are unaffected.

The endpoint authenticates by bearer token, never by cookie, so the check closes a transport rule rather than a session risk.

Can it be changed without a deploy?

Yes. Both settings live in the settings registry on the platform tenant. mcp.origin.enforcement is enforce (the default), report_only (log mcp.origin.would_refuse and let the request through) or off. Widening the allow list or switching to report_only is one update_setting call. If the settings cannot be read, the registry defaults apply: known clients keep working, and a foreign origin is still refused.

What does an assistant see when a tool fails?

A specific message, a code and a reference, never internals. lib/mcp/error-hygiene.ts is applied at the same door to every tools/call result:

  • A handler that throws is answered with "<tool> failed on the server. Check whether its change was made before trying again…", code: "tool_failed" and a reference. The cause is logged under that reference.
  • An error whose text names the server's insides is replaced: a duplicate key, a missing reference, a missing field, a bad UUID or a bad value become a plain sentence with a matching code (duplicate, not_found_reference, missing_field, invalid_id, invalid_value). Stack frames, file paths, SQL, relation and column names, PostgREST codes and permission wording become server_error with a reference.
  • A tool's own code is kept when it set one, because it is more specific than the failure class. A message that leaks nothing passes through unchanged.

So an assistant can tell its user what went wrong, and the operator can find the full cause in the logs by its reference.

How is it locked?

  • security-directory-c7-origin.test.ts (in the MCP API tests) drives the real MCP route: a foreign Origin with a valid bearer answers 403, no Origin and an allowed Origin pass, and report_only and off behave as described.
  • security-directory-c8-errors.test.ts (in the MCP API tests) drives a throwing tool and a leaking error through the route and asserts no stack, file path or SQL text reaches the client, and a reference is returned.
  • tests/lib/mcp/security-directory-c1-c6.test.ts holds the tool catalogue to the directory's annotation and naming rules.

Under the hood

Tools this page uses, in the order used:

Source files this page is checked against:

  • lib/mcp/origin-policy.ts
  • lib/mcp/error-hygiene.ts
  • app/api/mcp/[transport]/route.ts
  • lib/settings/registry.ts

Raw markdown: /docs-md/engineering-notes/the-mcp-door-checks-origin-and-cleans-errors

Last updated 2026-11-12