MCP authentication

MCP clients can authenticate with static workspace tokens or hosted OAuth. Static tokens keep quickstarts, controlled workspace testing, CI, and service agents simple. OAuth is the preferred hosted and enterprise path for delegated access, SSO/MFA-backed users, and stricter workspace policy.

For the account-created personal workspace path, see Personal workspace lifecycle.

Auth methods

Slab5 supports two MCP auth methods:

Static workspace tokens for quickstarts, controlled workspace testing, CI, and service agents.
Hosted OAuth for delegated human access, team workspaces, and enterprise security policy.

Both auth methods resolve to the same Slab5 tenant and workspace context before a tool runs. Scopes, module enablement, plan limits, audit events, and usage events apply either way.

Clients, grants, and scopes

An MCP client is whatever connects to Slab5 over MCP: ChatGPT, Claude, Cursor, a local script, or a service agent.

For static tokens, you can create multiple MCP clients in one workspace from the MCP Clients page by clicking New static token repeatedly. Each token gets its own name, secret, and selected scopes.

Example MCP clients

ChatGPT Support Assistant: support:read, support:write
Website CMS Publisher: cms:read, cms:write, assets:write
Analytics Reader: analytics:read, bi:read

That lets you revoke or narrow one integration without affecting the others.

A scope is a permission like assets:read or crm:write. It answers: "What app area and action is allowed?"

A grant is an authorization record for a subject. In MCP OAuth, the client signs in a user or subject, and the grant says: "This OAuth subject is allowed into this workspace with these scopes."

Grant = who is allowed.
Scopes = what that allowed identity can do.

Bearer tokens

Remote MCP configjson

{
  : var(--shiki-token-string)">"color: var(--shiki-token-parameter)">: var(--shiki-token-string)">"mcpServers": {
    : var(--shiki-token-string)">"color: var(--shiki-token-parameter)">: var(--shiki-token-string)">"slab5": {
      : var(--shiki-token-string)">"color: var(--shiki-token-parameter)">: var(--shiki-token-string)">"url": : var(--shiki-token-string)">"https://mcp.slab5.com/v1/w/your-workspace-slug",
      : var(--shiki-token-string)">"color: var(--shiki-token-parameter)">: var(--shiki-token-string)">"headers": {
        : var(--shiki-token-string)">"color: var(--shiki-token-parameter)">: var(--shiki-token-string)">"Authorization": : var(--shiki-token-string)">"Bearer YOUR_SLAB5_TOKEN"
      }
    }
  }
}

A static token carries its own workspace, so the bare https://mcp.slab5.com/v1 address also works for it. Prefer the workspace URL anyway: it is the address the console gives you, it is the same one an OAuth connection uses, and it makes the target workspace visible in the client's own configuration.

A static token used against a different workspace's address is refused rather than quietly served in its own workspace.

OAuth connections

Hosted MCP clients should use OAuth when they need delegated user access, team policy, SSO, MFA, or enterprise controls. OAuth connections still require active Slab5 workspace membership before any app-plane operation executes.

The MCP gateway verifies OAuth access tokens against the configured issuer. It resolves the token subject to a Slab5 user, resolves the selected account when present, and then resolves an active workspace membership before scopes and module checks run.

An OAuth connection must name its workspace in the path: https://mcp.slab5.com/v1/w/{workspace-slug}. A connection to the bare /v1 address is refused.

That refusal is deliberate. A static token cannot be ambiguous — the workspace is on the token record — but an OAuth token identifies a person, and a person may belong to several workspaces. With nothing naming one, the lookup falls to their oldest active membership, which is an accident of insert order rather than a choice: someone invited to a colleague's workspace before creating their own would connect and silently operate in the colleague's.

Header selection with x-slab5-workspace-id or x-slab5-workspace-slug still works for clients that cannot vary the URL, and the older workspace_id / workspace_slug query parameters are still read so existing connections keep working. Nothing emits the query form now; the path segment takes precedence over both.

MCP clients that support OAuth discovery use:

/v1/.well-known/oauth-protected-resource
/v1/.well-known/oauth-authorization-server

Discovery lives under the /v1 base path, not at the origin root. When a request to the MCP endpoint is missing authorization, the gateway returns a WWW-Authenticate challenge naming the metadata URL, so a client that follows the resource_metadata hint reaches the right document without constructing the URL itself.

OAuth workspace grants

Workspace owners and admins can add explicit OAuth workspace grants from the MCP Clients page. A grant is attached to one OAuth subject and one Slab5 workspace.

OAuth grants are a narrowing layer, not an elevation layer. The effective MCP OAuth scopes are:

workspace role scopes
intersect OAuth workspace grant scopes when a grant exists
intersect OAuth token permissions when those permissions name Slab5 scopes

If the OAuth token does not include a permissions list, Slab5 uses the allowed scopes from the workspace role and explicit grant. If no explicit OAuth workspace grant exists for the subject, Slab5 preserves the workspace role behavior so existing OAuth connections continue to work.

The last condition matters when the identity provider names its permissions differently from Slab5. A permissions claim that overlaps the available scopes narrows them. A claim that overlaps none of them is read as saying nothing about Slab5 authority rather than as denying all of it, and the workspace role decides — otherwise an owner holding every role scope would resolve to none, the connection would succeed, and the client would report an empty tool list with no error anywhere to explain it.

Use explicit grants when an OAuth-connected client should have less access than the signed-in user has in the Slab5 workspace. For example, an admin can keep normal admin access in the console while granting ChatGPT only crm:read and tasks:write through MCP.

Workspace-scoped URLs

Every MCP connection uses a workspace-scoped server URL, copied from the MCP Clients page. The same address serves both auth methods — there is no separate OAuth URL:

MCP server URL

https://mcp.slab5.com/v1/w/your-workspace-slug

The protected-resource metadata URL names no workspace:

Protected resource metadata URL

https://mcp.slab5.com/v1/.well-known/oauth-protected-resource

These two are different kinds of thing, and keeping them apart is what makes the connection work.

The server URL identifies a workspace. It is per-workspace on purpose: clients normalise or drop query strings when deciding whether two servers are the same, so an earlier ?workspace_id= form collapsed two workspaces into a single connection. A path does not collapse, so two workspaces are two connector entries with two tokens, and one client can hold several Slab5 connections at once.

The OAuth resource is the server: https://mcp.slab5.com/v1, and nothing else. RFC 8707 resource indicators name a protected resource, not each path within one, and an authorization server only issues tokens for resource URIs registered with it. The workspace does not appear in OAuth at all — it is resolved from the request path after the token is verified, which is an authorization detail of Slab5's rather than something the authorization server needs to know.

Do not put secrets in MCP server URLs.

Admin console lifecycle

Workspace owners and admins can create and revoke static MCP client tokens in the Slab5 console:

Create a workspace MCP client with a name and scope set.
Add, update, and revoke OAuth workspace grants for OAuth subjects.
Show the full token once after creation.
Store only the token prefix and hash.
List clients by name, client ID, prefix, status, timestamps, and scopes.
Revoke active clients after explicit confirmation.
Record create and revoke actions in audit logs and usage metering.

Members and readonly users cannot create or revoke static MCP client tokens. Credential actions are checked against active membership in the target workspace.

Workspace policy

Workspace admins can choose which MCP auth methods are allowed:

static_token: static MCP client tokens can be created and used.
oauth: static MCP client token creation and token use are blocked. MCP access must use hosted OAuth.
both: static tokens are allowed and hosted OAuth can also be supported.

Every workspace can choose any of the three, personal accounts included — an individual developer connects Claude or ChatGPT to their own workspace the same way a team does. Static token creation and gateway authentication are blocked immediately when a workspace is set to OAuth-only.

Recommended scopes

For the quickstart workflow, create a token with:

Quickstart scopes

crm:read
crm:write
tasks:read
tasks:write
activity:read
activity:write

Add cms:read, cms:write, analytics:read, and analytics:write for content operations or analytics governance workflows. Use audit:read only for tools or UI flows that inspect audit logs.

Environment example

For local apps or graph runtimes, keep the token in environment variables and interpolate it into the MCP client configuration at runtime:

.env.localbash

SLAB5_MCP_URL=https://mcp.slab5.com/v1
SLAB5_WORKSPACE_TOKEN=slab5_workspace_token_with_mcp_scopes

For hosted OAuth, configure the API gateway with the AuthKit issuer and MCP resource metadata URLs:

API OAuth environmentbash

SLAB5_AUTHKIT_ISSUER=https://your-subdomain.authkit.app
SLAB5_MCP_RESOURCE_URL=https://mcp.slab5.com/v1
SLAB5_MCP_PROTECTED_RESOURCE_METADATA_URL=https://mcp.slab5.com/v1/.well-known/oauth-protected-resource

Token rules

Tokens are scoped to exactly one workspace.
Tokens should carry only the scopes needed by the workflow.
Tokens should be revocable from the admin console.
Tokens must not expose secrets in structured errors, logs, or docs examples.
Every tool call should record token/workspace context in audit and usage events.

For token creation, rotation, storage, and revocation guidance, see Credential lifecycle.