Multi-Tenancy with Connections

When using Connections with MCP Auth, token storage and retrieval behavior depends on how the token is scoped to a user and/or tenant.

Token scope models

Connections support three token scope models:

1. User-level tokens
2. User-level tokens associated with a tenant
3. Tenant-level tokens

1) User-level tokens

User-level tokens are stored for a specific user within a connection.

• A user can have multiple tokens for the same connection when scopes differ.
• If a token is stored again for the same user with the same scope set, it replaces the existing token.
• Retrieval is done via the user token fetch endpoints.

2) User-level tokens associated with a tenant

These tokens are also fetched via the user token fetch endpoints, but include tenant association.

• They allow storing multiple tokens for the same user across multiple tenants within the same connection.
• Tokens are treated as separate records based on tenant association.
• Scope overlap does not collapse tenant-specific tokens; tenant association keeps them distinct.

This model is useful when the same person belongs to multiple customer tenants and needs tenant-specific external credentials.

3) Tenant-level tokens

Tenant-level tokens are scoped to a tenant and shared among its users.

• These tokens are typically used by multiple users in the same tenant.
• Access is controlled by tenant context and authorization (for example, a tenant role such as Tenant Admin).
• Retrieval is done via tenant-scoped token fetch patterns.

Choosing the right model

• Use user-level tokens when credentials are personal and not tenant-specific.
• Use user-level + tenant tokens when a user operates in multiple tenants and each tenant should have separate external credentials.
• Use tenant-level tokens for shared tenant integrations managed by tenant administrators.