Stochastic Deputy MCP

Structural tenant isolation for tool-using Model Context Protocol (MCP) agents.

This repository is the maintained reference implementation and reproducibility companion for The Stochastic Deputy: Structural Tenant Isolation for Tool-Using LLM Agents.

Paper

The Stochastic Deputy: Structural Tenant Isolation for Tool-Using LLM Agents is being released as an arXiv preprint by Mirza Samad Ahmed Baig, Syeda Anshrah Gillani, Asher Ali, and Muhammad Hamzah Siddiqui. The primary arXiv category is cs.CR (Cryptography and Security), with cs.AI as a cross-list.

The arXiv identifier and abstract-page link will be added here immediately after announcement. Until then, use the paper metadata in CITATION.cff when citing this work. The paper reports only aggregate operational measurements; this repository contains the fully synthetic runnable reference implementation.

The paper and its sanitized aggregate ancillary artifact are released under CC BY 4.0. Sharing or adapting either requires the attribution specified by that license. In a scholarly publication, provide attribution by citing the paper through CITATION.cff.

Related MCP server: AgentGuard MCP Server

Security property

The model can filter reservations by date and status, but it cannot name a tenant, property, hotel, organization, or authorization scope. Tenant scope is verified before MCP tool dispatch and passed to the server as trusted context. Every query applies that scope, and one egress mapping removes internal IDs and PII-like fields.

verified credential -> immutable scope -> MCP server -> scoped query -> redacted output
                                          ^
                                          |
                                no tenant argument exists

The included datastore is entirely synthetic. No company database, operational schema, endpoint, credential, record, identifier, or exact business cardinality belongs in this repository.

Current implementation

• TypeScript on Node.js 20 or later

• Official MCP TypeScript SDK v2

• MCP stdio server with a tenant-parameter-free tool schema

• Demonstration HMAC scope token with expiry and audience validation

• HTTP MCP resource server with Keycloak JWT verification

• MySQL repository that joins every query to the credential-bound tenant set

• Disposable Docker Compose stack with entirely synthetic multi-tenant data

• Egress minimization for internal identifiers and PII-like fields

• Unit, authorization, live integration, schema-regression, and privacy checks

The demonstration HMAC token is intentionally small and inspectable. It is not a production identity system. Production deployments should verify issuer, audience, signature, expiry, and authorization claims through their established OIDC/OAuth resource-server boundary and inject only the verified scope.

Quick start

Install exact dependencies and run the checks:

npm ci
npm run check

Create local demonstration credentials in PowerShell:

$env:SDM_DEMO_HMAC_KEY = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
$env:SDM_DEMO_TOKEN = npm run --silent mint-token -- tenant-alpha
npm run dev

The server uses stdout exclusively for MCP. Diagnostic messages go to stderr.

To inspect the built server:

npm run build
npx @modelcontextprotocol/inspector node dist/src/index.js

Live Keycloak and MySQL demonstration

Docker is required for the live demonstration. Start the disposable infrastructure, then start the HTTP MCP resource server:

npm run demo:infra:up
npm run demo:server

In another terminal, run the end-to-end verification and then stop the stack:

npm run demo:e2e
npm run demo:infra:down

The test obtains client-credentials tokens for two synthetic identities and checks independent tenant confinement, JWT signature validation, audience and expiry enforcement, rejection of injected tenant arguments, and output minimization. It also checks that missing and tampered tokens receive HTTP 401.

The committed usernames and secrets are intentionally obvious local-demo values. Services bind only to loopback (3000, 3307, and 8180), MySQL uses temporary storage, and no production endpoint, account, schema, or credential is required. Do not reuse any demo value outside this disposable stack.

MCP tool

list_reservations accepts only:

• from: optional earliest arrival date

• to: optional latest departure date

• status: optional reservation status

• limit: optional result limit

Unknown arguments are rejected. In particular, an injected tenantId argument fails schema validation before the handler runs.

Repository boundaries

Safe to maintain here:

• Synthetic fixtures and generators

• Generic authorization adapters

• MCP schemas and enforcement tests

• Aggregate research results

• Figure and table reproduction code

Never commit:

• Production source or configuration copied from an internal deployment

• Database dumps, row-level extracts, raw prompts, traces, or tool outputs

• Credentials, tokens, private keys, certificates, endpoints, or private IPs

• Operational table/column names, tenant IDs, reservation IDs, or property names

• Exact company database size or business cardinalities

See PRIVACY.md, SECURITY.md, and docs/architecture.md before contributing.

Preprint and releases

The repository is public alongside the author-identified preprint. After arXiv assigns an identifier, the README and CITATION.cff will be updated with the permanent preprint URL. Versioned software archives and their persistent identifiers will be linked here when available.

Project status and licensing

The code is an early research reference implementation released under the Apache License 2.0. The paper and sanitized aggregate research artifact are separately licensed under CC BY 4.0. If this software contributes to a scholarly publication, cite the associated paper using CITATION.cff. The private package flag prevents accidental npm publication; it does not restrict the open-source license.