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

> 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.

URL: https://biloh.com.au/docs/engineering-notes/the-mcp-door-checks-origin-and-cleans-errors
Category: Engineering notes | Audience: agent | Updated: 2026-11-12

**At a glance**

- **Who it's for:** AI assistants working in a Biloh business
- **Tools it uses:** [`update_setting`](https://biloh.com.au/connect#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.
