Multi-Tenant Remote MCP Server Design Guide

A remote MCP server that serves many customers from one deployment can leak one tenant's tools, data or upstream credentials to another through mechanisms that ordinary SaaS isolation reviews do not look at. Access tokens that are valid for the whole service rather than one tenant, tool lists cached by a shared gateway, state handles that a model carries between calls, and a single upstream credential used for every customer are all MCP-specific ways to break tenancy. This guide covers the design decisions that are particular to MCP: how to bind token audience to a tenant, how to keep tool, prompt and resource lists and cross-call state separated now that the protocol has no sessions, and how to hold upstream credentials per tenant. It is for teams building or operating hosted MCP servers and gateways. General isolation models (silo, pool and bridge) and database enforcement are in the Multi-Tenant SaaS Authorisation and Tenant Isolation Guide, and the single-tenant baseline is in the Remote MCP Server Hardening Guide. Protocol details refer to MCP revision 2026-07-28 as published on modelcontextprotocol.io, checked on 13 November 2026.

Key takeaways

Tenant context comes from the token, and only the token. Revision 2026-07-28 removed protocol sessions, so every request must carry its own authority. Derive the tenant from a validated access token, never from a path, header, tool argument or model output alone.
Make the audience tenant-specific where you can. A per-tenant canonical server URI (for example a tenant path) lets RFC 8707 and RFC 9728 bind each token to one tenant's endpoint, so a token minted for tenant A fails audience validation at tenant B.
Lists may differ by caller, so caches must too. The specification lets tools/list vary by the authorisation presented, and any list that varies must carry cacheScope: "private", or a shared gateway may serve one tenant's tools to another.
Handles and requestState are attacker-controlled input. Check the caller's tenant and principal against every state handle, and integrity-protect any requestState that affects authorisation, binding it to the principal with a short expiry.
Upstream credentials are per tenant, never shared. Store each tenant's upstream tokens and keys in a tenant-scoped namespace, keyed by tenant, user and issuer, so one compromise or one bug cannot reach every customer's downstream systems.

What MCP changes about multi-tenancy

Most of a multi-tenant MCP server is ordinary SaaS: a request arrives, a tenant is identified, data access is scoped. Four properties of MCP add risks of their own.

No sessions: revision 2026-07-28 removed the initialize handshake and the Mcp-Session-Id header. A server built for an earlier revision may have tied tenant context to the session; that context must now be rebuilt from the access token on each POST. The transport says a server that only supports this revision should ignore Mcp-Session-Id and not mint or echo session IDs.
The model carries state: cross-call state now travels as server-minted handles in tool arguments and as requestState in multi round-trip requests. Both pass through the client and the model, so a prompt-injected or malicious client can substitute another tenant's value.
Capabilities are discoverable per caller: tools, prompts and resources are listed by the server, may differ by tenant, and are often cached by clients and gateways.
The server is a credential broker: it calls upstream APIs for each user. The specification forbids passing the client's token upstream, so the server holds separate upstream credentials, and how it partitions them decides the blast radius.

OWASP's API1:2023 Broken Object Level Authorization and API4:2023 Unrestricted Resource Consumption describe the generic failures behind most cross-tenant MCP incidents: an object identifier accepted without checking ownership, and one client exhausting shared capacity. See the Multitenant AI application security guide for retrieval, prompt cache and model-level isolation, which this page does not repeat.

Tenant addressing and token audience

The authorisation specification requires clients to send the RFC 8707 resource parameter with the canonical URI of the MCP server, and requires servers to accept only tokens issued for them as audience and to reject any other token. The specification lists https://mcp.example.com/server/mcp as a valid canonical URI "when path component is necessary to identify individual MCP server". RFC 9728 notes that path-based protected resource metadata "is required in some multi-tenant hosting configurations", and the MCP discovery rules let a server publish metadata for a path endpoint at /.well-known/oauth-protected-resource/ plus that path. Together these allow one host to present each tenant as its own protected resource.

Addressing pattern	Example canonical URI	Audience binding	Trade-offs
Shared endpoint, tenant from token claim	`https://mcp.example.com/mcp`	One audience for all tenants; tenant derived from a claim or from the subject's directory record	Simplest to operate; a token for any tenant passes audience validation, so every tool handler must enforce tenant scope correctly
Per-tenant path	`https://mcp.example.com/t/acme/mcp`	Audience per tenant; metadata at `/.well-known/oauth-protected-resource/t/acme/mcp`	Strong binding on one host; clients must be configured with the tenant URL; the path must be checked against the token, not trusted alone
Per-tenant host	`https://acme.mcp.example.com/mcp`	Audience per tenant; separate TLS names and metadata	Cleanest separation and easy routing; more certificates and DNS to manage; tenant names visible in DNS
Per-tenant authorisation server or issuer	Issuer such as `https://auth.example.com/acme` listed in that tenant's metadata	Issuer and audience both tenant-specific	Fits enterprise customers who bring their own identity provider; the server must map each issuer to exactly one tenant

Validation rules for every request

Signature and issuer: verify the token against the keys of an issuer that is allowed for the addressed tenant, not any issuer the service trusts. MCP clients must key client credentials by issuer and must not reuse them with a different authorisation server; mirror that on the server by keeping an issuer-to-tenant map.
Audience: the audience must equal the canonical URI the request arrived on (per-tenant patterns) or the shared service URI (shared pattern). Reject tokens minted for another tenant's endpoint with HTTP 401.
Tenant consistency: where a tenant appears in the path, host and token, all three must agree. A mismatch is an attack or a client bug; reject and log it.
Scope: evaluate scopes within the tenant. The specification requires servers to account for scope hierarchies; a broad scope in tenant A grants nothing in tenant B.
Expiry: keep access tokens short-lived, as the specification recommends, so a token leaked from one tenant's client has a short useful life.

Choosing a pattern: a small provider serving one organisation's business units can use the shared endpoint if tenant scoping is enforced centrally in middleware and tested. A SaaS provider serving unrelated customers should use per-tenant paths or hosts, and add per-tenant issuers for customers that federate their own identity provider. See the MCP Authorisation Specification Guide for the full flow.

Tool, prompt and resource lists per tenant

The tools specification says tools/list must not vary per connection or as a side effect of other requests, but may vary by the authorisation presented, for example returning only the tools the caller's scopes permit. That makes per-tenant tool catalogues legitimate, and makes caching the main risk.

Mechanism	Cross-tenant risk	Design rule
`cacheScope` on list and read results	A shared gateway caches a `"public"` list and serves tenant A's tools or resources to tenant B	Use `"private"` for any result filtered by tenant, user or scope; the caching specification says private caches must not be shared across authorisation contexts, and every page of a list must carry the same scope
`ttlMs`	A long freshness hint keeps a revoked tool visible after a tenant's entitlement changes	Short TTLs for tenant-filtered lists; emit list-changed notifications on entitlement changes
`subscriptions/listen` streams	Change notifications for one tenant's resources reach a listener from another	Authorise the listen request like any other, and send notifications only for objects the listening principal can read
Tenant-defined tools or prompts	One tenant uploads a tool description that poisons a catalogue shared with others	Keep tenant-authored definitions in that tenant's catalogue only, and review them as code. See the MCP Tool Poisoning Detection guide
Resource URIs	A guessed or model-supplied URI reads another tenant's resource	Authorise every `resources/read` against the caller's tenant; never treat a URI as proof of access

The caching specification is explicit that servers must apply per-primitive access controls and must not rely on cacheScope alone. Hiding a tool from a tenant's list is a usability feature; the authorisation check inside tools/call is the control.

Cross-call state without sessions

Stateful work (a draft, a browser context, a database transaction) is now carried by values the client echoes back. Each carrier needs tenant binding.

State carrier	What the specification says	Tenant control
Tool handles (for example `basket_id`)	Non-normative guidance: for authenticated servers a handle is a name, not a capability; validate the caller's authorisation against the handle on every call; keep handles opaque and state their lifetime	Store tenant and owner with each handle; on every call check both against the token; return a not-found style error for other tenants' handles so existence is not revealed
`requestState` in multi round-trip requests	Servers must treat it as attacker-controlled; must integrity-protect it (HMAC or AEAD) if it influences authorisation, resource access or business logic; should include the authenticated principal, a short expiry and the originating request	Add the tenant identifier inside the protected payload, use per-environment keys, and enforce single use server-side where an action must not repeat
Upstream elicitation and OAuth flows	Servers encode their own correlation identifiers in `requestState`	Bind the OAuth `state` and the resulting upstream token to tenant and user before storing
Server-side stores and queues	Not defined by the protocol	Namespace keys by tenant; no global variables or singletons holding user data

Because multi round-trip requests were designed so that no shared storage or sticky load balancing is needed, any instance can receive a retry. That is good for scale and means verification keys and tenant maps must be available to every instance, with no fallback to "trust the payload". For handling user prompts during these flows, see the MCP Sampling and Elicitation Security Guide.

Per-tenant upstream credentials

The security considerations state that the token used at an upstream API is a separate token issued by the upstream authorisation server, and that the MCP server must not pass through the token it received. Proxy servers that use a static client ID with a third-party authorisation server must obtain user consent for each dynamically registered client before forwarding. In a multi-tenant server these upstream credentials are the most valuable thing it holds.

Pattern	When it fits	Isolation controls
Per-user delegated upstream OAuth	Upstream SaaS acting as the user (mail, files, tickets)	Store tokens keyed by tenant, user and upstream issuer; encrypt with a tenant-specific data key; revoke on user removal or tenant offboarding
Per-tenant service credential	Tenant-owned systems where one integration account per customer is acceptable	One credential per tenant in a tenant-scoped vault path; least privilege inside that tenant's upstream; rotation per tenant
Customer-supplied API keys	Customers bring their own keys for model or data providers	Write-only after entry, tenant-scoped storage, no display or logging, usage limits per key
Token exchange with workload identity	Upstream accepts tokens from your own platform	Exchange for narrowly scoped, short-lived upstream tokens carrying tenant and user context. See the OAuth Token Exchange and Delegation Guide
One shared credential for all tenants	Avoid	If unavoidable during migration, enforce tenant scoping in a single policy layer and treat removal as a priority

Lookup must use the verified tenant: fetch upstream credentials using the tenant and subject from the validated token, never a tenant value supplied in tool arguments.
Separate the control plane: deployment and hosting tokens can reach every tenant at once. In the Smithery.ai MCP hosting breach, a build path flaw exposed a hosting token for an organisation of more than 3,000 apps, mostly hosted MCP servers, and researchers captured one client's API key from a running server. Scope platform tokens narrowly and keep them off build hosts.
Offboarding: deleting a tenant must revoke and delete its upstream tokens, keys and handles, and the deletion should be verifiable.

See the Confused Deputy in AI Agents Guide for why a server that holds many users' credentials is a deputy that must re-check every request.

Gateways and intermediaries

Many multi-tenant deployments put a gateway in front of MCP servers for routing, rate limiting and policy. The transport mirrors the method and tool or resource name into Mcp-Method and Mcp-Name headers, and tool parameters marked with x-mcp-header into Mcp-Param-{name} headers. These headers are client-supplied.

Route on validated identity: intermediaries that route or rate-limit by tenant should take the tenant from the validated token. The transport says such intermediaries should reject requests whose protocol version does not require header and body validation, rather than trust unvalidated headers.
Servers recheck: any server that processes the body must reject header and body mismatches with HTTP 400 and error -32020 (HeaderMismatch).
No tenant authority in parameters: a tenant or region parameter mirrored with x-mcp-header is useful for routing hints but carries no authority, and the tools specification says sensitive parameters should not be mirrored at all.
Per-tenant quotas: the tools specification requires servers to rate limit tool invocations. Set limits per tenant and per user so one tenant's agent loop cannot exhaust shared capacity or shared upstream quotas.

See the MCP Gateway and MCP Server Governance Guide.

Implementation and testing

Write the tenant model: choose the addressing pattern, list which issuers each tenant may use, and document where tenant context is derived (one middleware function, not each handler).
Publish per-tenant metadata: for path or host patterns, serve RFC 9728 metadata per tenant with a resource value identical to the tenant URI, as RFC 9728 requires clients to check.
Enforce in monitor mode first: log audience, issuer and tenant mismatches for one release, then reject. Keep a short-lived, per-client exception list rather than a global bypass.
Bind state: add tenant and owner to handles and to protected requestState; set cacheScope to private on every tenant-filtered result.
Partition credentials: migrate upstream credentials into tenant-scoped storage with per-tenant data keys; remove shared credentials.
Prove it with cross-tenant tests: for every tool, resource and prompt, call with tenant B's token using tenant A's handles, URIs, requestState and paths, and assert denial. Repeat through the gateway with caching on. Add these tests to CI. See the MCP Security Testing Guide.
Roll back safely: deploy validation changes blue-green, so a faulty rule can be reverted without disabling authentication or tenant checks.

Where identity fits

A multi-tenant MCP server holds three layers of non-human identity: its own workload identity, the per-tenant integration credentials it uses upstream, and the OAuth clients that agents use to reach it. Each needs an owner, a tenant label, least privilege and a rotation date. Agents connecting on behalf of users should be distinguishable from users in tokens and logs. See the Agent Identity and Access Guide.

Detection and measurement

Log per request: tenant, subject, client ID, issuer, audience, Mcp-Method, Mcp-Name, handle identifiers (hashed), outcome and upstream credential used, without tokens or raw arguments.
Alert on: audience or issuer mismatches, tenant mismatches between path and token, handle lookups that resolve to another tenant, requestState verification failures, and one client touching more than one tenant.

Metric	Target
Requests accepted with a tenant-bound audience	100 per cent for per-tenant patterns
Tenant-filtered results returned with `cacheScope: "private"`	100 per cent, checked in CI
Cross-tenant test cases passing (denied as expected)	100 per cent on every release
Upstream credentials stored outside a tenant-scoped namespace	Zero
Time to revoke all credentials for an offboarded tenant	Under 24 hours, verified

Common failure patterns

Service-wide audience with handler-level checks: every token passes audience validation and one handler forgets the tenant filter.
Tenant from the URL only: the server trusts /t/acme/ in the path without checking that the token belongs to that tenant.
Public cache on private lists: tenant-filtered tools/list or resources/read results marked public and served by a shared gateway.
Guessable or unchecked handles: sequential identifiers, or handles looked up without comparing the stored tenant to the caller.
Unsigned requestState: base64 JSON carrying a tenant or user identifier that a client can edit.
Session-era assumptions: code that still keys tenant context on Mcp-Session-Id after upgrading to revision 2026-07-28.

Framework mapping

Framework	Reference	Design area
NIST SP 800-53 Rev. 5	AC-3 Access Enforcement, AC-4 Information Flow Enforcement, AC-6 Least Privilege	Tenant-scoped authorisation for tools, resources and handles
NIST SP 800-53 Rev. 5	SC-4 Information in Shared System Resources, SC-39 Process Isolation, SC-2 Separation of System and User Functionality	Caches, state stores and shared runtimes
NIST SP 800-53 Rev. 5	IA-5 Authenticator Management, IA-9 Service Identification and Authentication, AU-2 Event Logging	Per-tenant upstream credentials, audience validation, tenant-aware logs
NIST CSF 2.0	PR.AA-03, PR.AA-05, PR.DS-01, PR.DS-02, DE.CM-03	Authentication, least privilege, data protection, monitoring
OWASP API Security Top 10 2023	API1:2023 Broken Object Level Authorization, API4:2023 Unrestricted Resource Consumption	Handles and URIs, per-tenant quotas
MITRE ATT&CK	T1528 Steal Application Access Token, T1550.001 Application Access Token, T1078.004 Cloud Accounts	Theft and reuse of tokens and upstream credentials

Practitioner checklist

Derive tenant context in one middleware layer from the validated token only.
Use per-tenant paths or hosts as canonical URIs for unrelated customers, with RFC 9728 metadata per tenant.
Map each allowed issuer to exactly one tenant and reject tokens from other issuers.
Reject requests where path, host and token tenants disagree.
Mark every tenant-filtered list or read result cacheScope: "private" with short TTLs.
Store tenant and owner with every handle and check both on every call.
Integrity-protect requestState with the principal, tenant, expiry and originating request inside.
Keep upstream credentials in tenant-scoped storage with per-tenant keys; remove shared credentials.
Rate limit per tenant and per user, at the gateway and in the server.
Run cross-tenant tests for every tool, resource and prompt in CI.

Multi-Tenant Remote MCP Server Design: Token Audience, Tool Lists and Per-Tenant Credentials