MCP authentication and permissions

Every request to POST /mcp requires an OAuth access token issued for the exact MCP resource audience. Chataigne verifies the token, active user session, OAuth client, consent and scopes on every request.

Effective authorization

A business tool is authorized by the intersection of three controls:

consented OAuth scopes
  ∩ current role permissions
  ∩ current membership of the target resource

The server resolves the target’s real owning organization from the database. A caller cannot authorize a catalog item, order or conversation by supplying an unrelated location identifier.

Caller	Tenant rule	Scope rule
Merchant user	Requires a live membership in the location or parent business organization and the required role permission	Always required
Global Chataigne administrator	May address every organization and location without membership	Always required
Revoked or banned user	Denied on the next request	Not applicable
Disabled OAuth client or revoked consent	Denied on the next request	Not applicable

Global administrator access is broad but never implicit. The token must contain the required read or write scope. Grant production write scopes only to trusted clients.

Scopes

Identity scopes are openid, profile, and offline_access. Business scopes follow the permission identifier format resource.action.

Domain	Read scopes	Write scopes
Workspaces	`businessOrganization.read`, `location.read`	—
Location settings	`storeSettings.read`, `orderSettings.read`, `openingHoursSettings.read`, `deliverySettings.read`, `paymentMethodSettings.read`, `settings.read`	—
Ordering status	`locationStatusSettings.read`	`locationStatusSettings.write`
Catalog	`catalog.read`	`catalog.updateAvailability`
Orders	`orders.read`	`orders.write`
Customers	`customers.read`	—
Conversations	`conversations.read`	`conversations.write`
Analytics	`analytics.read`	—
Discounts	`discounts.read`	—
Integrations	`integrations.read`	—
Additional settings sections	`ai.read`, `loyalty.read`, `referrals.read`, `notifications.read`	—

Tools whose static scope is absent do not appear in tools/list. Calling a hidden tool directly does not bypass the check. chataigne_location_settings_get additionally checks the granular scope for every requested section and fails the whole call if one section is not authorized. Platform-administration scopes and their additional live-role checks are documented only in the gated Admin section.

Token lifecycle

Access tokens are audience-bound to the canonical MCP URL.
Authorization Code uses PKCE.
Refresh tokens rotate.
A current Better Auth session, active user, enabled OAuth client and matching consent are required.
Memberships and role permissions are read live, so access removal takes effect on the next MCP request.

Recommended grants

For an assistant that only answers operational questions, start with:

openid profile offline_access
location.read catalog.read orders.read
customers.read conversations.read analytics.read

Add each write scope only when the client is trusted and the operational action is required. Write tools can also be disabled platform-wide independently of OAuth consent.

Authentication failures

Authentication failures return HTTP 401 and a WWW-Authenticate header pointing to protected-resource metadata. Tool-level permission failures return a safe MCP error with code MCP_RESOURCE_FORBIDDEN; the message does not reveal whether a cross-tenant identifier exists.

​Effective authorization

​Scopes

​Token lifecycle

​Recommended grants

​Authentication failures

Effective authorization

Scopes

Token lifecycle

Recommended grants

Authentication failures