mcp-server — tenant-safe, read-only

A Model Context Protocol server exposing operational tools over a multi-tenant dataset to any MCP client, with the tenant bound server-side and never present in the published tool schema.

The argument

An MCP server publishes its tool schema to whatever client connects — Claude Desktop, an IDE, a third-party agent. That makes the schema a trust boundary, and it changes the calculus compared to an agent you own end to end.

If a tool took a company parameter, tenant selection would be delegated to a model on the other side of the connection: one you did not write, cannot audit, and whose version can change without telling you. No prompt on your side constrains it, because the prompt lives over there.

So the tenant is not a parameter. It is read once, at process start, from the server's own configuration:

TENANT = resolve_tenant()   # from MCP_TENANT_ID; fails hard if unset

Cross-tenant access is not "unlikely" or "blocked by instructions" — there is no argument in which to express it. That is the entire design, and everything below exists to prove it holds rather than assert it.

This matches how MCP is actually deployed: one server process per user, launched by the client with its own configuration. Identity belongs to that config, not to the conversation.

Verified, not asserted

MCP_TENANT_ID=acme python scripts/check_isolation.py   # 5 properties
python scripts/check_e2e.py                            # real stdio handshake

check_isolation.py asserts, against the running server:

#	Property
1	No published tool exposes a tenant-like parameter (company, tenant_id, merchant, …)
2	Every tool is annotated read_only_hint
3	Executing every published tool leaks no other tenant's canary
4	Injecting company=<other> into a call returns nothing belonging to that tenant
5	Without MCP_TENANT_ID the server fails to start instead of defaulting

Check 3 enumerates whatever the server publishes and builds arguments from each schema, rather than calling a hardcoded list. A hardcoded list would silently skip exactly the tool someone adds later — which is the case worth catching.

check_e2e.py starts the server as a subprocess and drives it through initialize → list_tools → call_tool over stdio: proof it speaks the protocol, not just that the Python objects behave.

The checks are themselves checked

MCP_UNSAFE_MODE=1 publishes a deliberately broken tool that accepts company and honours it. The isolation check must go red under it:

MCP_TENANT_ID=acme MCP_UNSAFE_MODE=1 python scripts/check_isolation.py
# FAIL  no tool exposes a tenant parameter   -> list_orders_unsafe.company
# FAIL  no output contains another tenant's canary -> leaked: ['globex']

A guard that has never gone red has not been shown to detect anything. Shipping the broken variant is what makes the green run mean something.

Run it

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
MCP_TENANT_ID=acme python -m server.main    # stdio

In an MCP client (Claude Desktop and similar), register one process per tenant:

{
  "mcpServers": {
    "acme-ops": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "cwd": "/path/to/mcp-server",
      "env": { "MCP_TENANT_ID": "acme" }
    }
  }
}

Tools

All read-only. None takes a tenant argument.

Tool	Returns
sales_summary(start_date, end_date)	Order count and total for a date range
list_orders(status)	Orders with status paid / pending / refunded
top_customers()	Customers ranked by total spend

Structure

mcp-server/
├── server/
│   ├── tenant.py   # the only place a tenant is decided
│   ├── data.py     # synthetic multi-tenant dataset with per-tenant canaries
│   └── main.py     # MCP server; tools + the gated unsafe variant
├── scripts/
│   ├── check_isolation.py   # the 5 properties above
│   └── check_e2e.py         # stdio protocol handshake

The dataset is fictional so the repo is clonable and runnable as-is.

Scope

This is a portfolio implementation of one pattern, not a product. See SECURITY.md for what it does and does not cover — notably that MCP_TENANT_ID stands in for a verified token, which is what a real deployment would use.