Multi-Tenant MCP: Sessions, Secrets, and Isolation Patterns

Multi-tenant MCP is where demos become security reviews. This page maps tenancy patterns to official MCP session and security requirements.

Official rules that constrain tenancy design

Sessions (Streamable HTTP)

From Transports — session management:

• Server MAY assign MCP-Session-Id at init
• Session ID SHOULD be globally unique and cryptographically secure
• Client MUST send it on subsequent requests if issued
• Servers that require sessions SHOULD reject missing session with 400

From Security Best Practices — session hijacking:

• Servers that implement authorization MUST verify all inbound requests
• MUST NOT use sessions for authentication
• Bind session-related data to user-specific information (e.g. user_id:session_id keys)
• Avoid predictable session IDs

Tokens and proxies

• MUST NOT accept tokens not issued for this MCP server (no passthrough)
• OAuth proxy designs need per-client consent (confused deputy section)

Tools

Servers MUST validate inputs, implement access controls, rate-limit, sanitize outputs (tools security).

Tenancy patterns

1. Per-tenant deployment (simplest isolation)

tenant-A → https://a.example/mcp  (own secrets)
tenant-B → https://b.example/mcp  (own secrets)

Pros: hard isolation, clear blast radius
Cons: more instances, more deploy automation

Fits managed hosts that spin deployments cheaply (product concern).

2. Shared process, strong identity (hard mode)

One deployment; every tools/call authorized against authenticated principal + tenant claim.

Pros: density
Cons: one bug = cross-tenant incident

Requires ironclad authz middleware and careful resource URIs.

3. Gateway for SaaS + host for custom (split plane)

• Gateway: multi-tenant OAuth to commodity apps
• Hosted MCP: your multi-tenant product logic

See gateway vs hosting. Gateways must still follow confused-deputy mitigations.

Secrets patterns

Never put tenant secrets in mcplambda.yaml or git — only build/run config in yaml (docs).

Session + auth checklist

• Authn on every request (not only session cookie/header)
• Session IDs unguessable if used
• Session store keys include tenant/user id
• Tool layer checks tenant entitlement
• Rate limits per tenant
• Audit: who called which tool when

Progressive discovery at scale

Multi-product agents accumulate huge tool lists. Hosts should use progressive discovery (client best practices) so one tenant’s connector sprawl doesn’t destroy context for everyone.

Worked scenario: The shared process that leaked context

An early multi-tenant design used one MCP process and trusted a tenant_id argument from the model. A prompt injection supplied another tenant’s id and read data.

You redesign: authenticate the caller, bind tenant from the token, never from model-supplied ids alone. Session IDs (if used) are cryptographically random and never treated as authentication. High-risk customers get per-tenant deployments; others share only with hard authz checks on every tools/call.

Secrets are per-tenant and injected at runtime—not global admin tokens.

Checklist for this topic

• Derive tenant from verified auth identity, not tool args alone
• Do not use sessions as authentication
• Per-tenant secrets; no global admin PAT
• Authorize every tools/call
• Prefer per-tenant deploys when isolation requirements are high
• Audit who called which tool for which tenant

Topic-specific failure modes

Related guides

Securing remote · Support agents · Auth patterns

In practice: threat model questions

Answer before coding tenancy:

1. What is the blast radius of one stolen client token?
2. Can a tool argument select another tenant’s data?
3. Are session IDs guessable or reused across users?
4. Do logs include cross-tenant identifiers unsafely?
5. Who approves a new high-risk tool for all tenants?

If answers are fuzzy, default to per-tenant deployments until the model is clear.

Pattern choice cheat sheet

Start stricter than you think you need; relaxing isolation is easier than tightening after a breach narrative.

Takeaways

For Multi-Tenant MCP: Sessions, Secrets, and Isolation Patterns, remember three things:

1. Be specific to this problem — the worked scenario “The shared process that leaked context” is the failure mode you should design against, not a generic outage narrative.
2. Isolate secrets and session state per tenant; never reuse a shared process for untrusted tenants without hard boundaries.
3. Prefer per-tenant credentials and explicit session identifiers over ambient global env.

If you only remember one habit: design for the failure mode where tenant A must never see tenant B’s tools or data.

Sources

• Transports — session management
• Security Best Practices
• Authorization — 2025-11-25
• Tools security
• Client best practices

Next steps

Securing remote MCP · Support agents use case