Engineering notesView as Markdown ↗

Making a multi-connector MCP setup safe to act on

In plain terms

If your assistant is connected to more than one business, Biloh helps it act on the right one. Every reply names the business it touched. A change can state which business it is meant for, and a mismatch stops it before anything happens. Platform actions that can't be undone need a second confirming step.

When an agent holds several tenant connectors at once, the risk isn't data leakage (that's sealed server-side) — it's acting on the wrong tenant by mistake. The fix is layered: make the tenant visible, make it assertable, and gate the irreversible actions. Visibility alone is not enough.

At a glance

Who it's for:
Engineers building on Biloh
What a person approves:
Each connection works on one business only, and cannot reach another.
Checked against the code:
2026-08-20

An AI agent can hold several Biloh connectors at once — one per tenant, plus a platform-admin connector — and they look almost identical in the tool list. The danger is not that one connector reads another's data (that is sealed by a tenant-bound token, row-level security, and write gateways, independent of the agent). The danger is intent: calling the right tool on the wrong connector.

Biloh solves this in three layers, cheapest first: make the tenant visible, make it assertable, and gate the actions you can't undo. Visibility alone — the most common instinct — is not enough.

Layer 1 — make the tenant visible

Two signals, on by default:

  • Connector identity. Each connection advertises itself as biloh · <Tenant> (<MODE>), where mode is LIVE (a real tenant), TEST (a tenant flagged as test data), or PLATFORM (the cross-tenant admin surface). Two real tenants are both LIVE — so the name distinguishes them and the mode separates a tenant from the platform.
  • A per-response stamp. Every tool result carries meta.tenant { id, name, mode }. Because it is on every call, the last result an agent received always tells it which tenant it just touched.

A subtle implementation note: the MCP handler is built once per process, so the server's identifying info is otherwise static across connections. Per-connection identity is therefore applied by rewriting the protocol initialize response — fail-safe, so any anomaly returns the original handshake untouched rather than risking the connection.

Layer 2 — make the tenant assertable (a misroute should fail)

Visibility helps a careful reader. It does nothing for a mistake already in flight. So a write can carry an optional expected_tenant: the tenant you intend to act on, by name or id.

If it doesn't match the connector you're on, the call returns expected_tenant_mismatch and the handler never runs. A misroute stops instead of silently going through. The argument rides the same central schema-augmentation as cross-tenant routing and is enforced once, at the single wrapper every tool call passes through — so it covers the whole tool surface without per-tool code.

Optional by default, mandatory by setting

A tenant can make the assertion compulsory on every write by enabling mcp.writes_require_expected_tenant. On such a tenant, omitting it fails before anything happens:

code: expected_tenant_required
detail: This tenant requires expected_tenant on all write calls
        (mcp.writes_require_expected_tenant is enabled).

This is a first-call surprise for any new integration, and it is worth designing around rather than discovering: pass expected_tenant on every write from the start. It costs nothing on tenants that don't require it, and it converts a whole class of misroute from silent to loud. Reads are unaffected.

Platform connectors name their target explicitly

The platform connector can act across tenants, so when it calls a tenant-scoped tool it must say which tenant:

Platform PAT must include target_tenant_id when calling a tenant
tool. Use list_all_tenants to discover tenant ids.

Tenant-bound callers omit target_tenant_id entirely — their tenant comes from the session. The route validates and strips the parameter before the handler runs, so handler behaviour is identical either way. The practical consequence: a platform connector is not a drop-in substitute for a tenant connector, and code that assumes it is will fail on the first tenant-scoped write.

The principle: data isolation and intent safety are different problems. One is enforced by the database; the other has to be enforced by affordances the caller opts into.

Layer 3 — gate what you can't undo

Two-phase confirm-gates protect the irreversible actions. The first call returns a preview plus a deterministic confirm_token and mutates nothing; only a second call carrying the matching token executes.

The scoping rule matters more than the mechanism: gate by operation, not by keyword. Archiving a tenant is irreversible — gated. Creating a tenant is gated too (it completes the lifecycle pair). Minting an access token is revocable — so it is deliberately left ungated. "Sounds dangerous" is not the test; "can't be undone" is.

A gate is only safe to add after an audit confirms nothing automated calls the tool — otherwise you break provisioning. In this build the audit showed zero code-level callers, so the gate had zero blast radius.

What each layer is locked by

Every layer ships with a spec test written before the code, so the guarantee can't quietly regress:

  • The mismatch guard has a test asserting a wrong expected_tenant returns the error code and the handler does not run.
  • Each confirm-gate has a test asserting the no-token call previews and mutates nothing, a wrong token errors, and the matching token executes.
  • The identity rewrite is fail-safe by construction and tested against a malformed handshake.

Locked by tests/lib/mcp/expected-tenant-guard.test.ts, which asserts a call whose expected_tenant does not match fails with expected_tenant_mismatch before the handler runs.

Next steps

Under the hood

Source files this page is checked against:

  • lib/mcp/server-instructions.ts
  • lib/mcp/registry.ts

Raw markdown: /docs-md/engineering-notes/multi-tenant-mcp-safety

Last updated 2026-08-20