@better-auth/mcp + @better-auth/cimd)
to authenticate MCP clients such as Claude Desktop, Claude Code, Cursor, and
ChatGPT.
How OAuth 2.1 Discovery Works
When an MCP client connects tohttps://<your-workspace-host>/api/mcp without
a token:
- Challenge (
401 Unauthorized) - Less returns an RFC 9728WWW-Authenticateheader pointing to/.well-known/oauth-protected-resource. - Metadata Discovery - The client fetches Protected Resource Metadata
(
/.well-known/oauth-protected-resource) and Authorization Server Metadata (/.well-known/oauth-authorization-server). - Client Identification - Clients identify themselves either via Client
ID Metadata Documents (CIMD) (
mcp-2026-07-28) or Dynamic Client Registration (/api/auth/oauth2/register). - Browser Sign-In & Workspace Consent (
/auth/consent) - Your browser opens to Less. After signing in, you tick one or more workspaces to authorize, pick a default, and click Allow access. - Resource-Bound Access Tokens - Less issues an audience-bound JWT access
token (
aud: https://<your-workspace-host>/api/mcp) scoped to your user and the workspaces you selected (subscription_idis the default;allowed_subscription_idsis the full set), verified via/api/auth/jwks.
Multiple workspaces
- Single connector (
/api/mcp) - authorize several workspaces on the consent screen. The agent useslistWorkspaces/switchWorkspaceto move between them.switchWorkspaceis remembered for that user + MCP client. - Pinned connector (
/api/mcp/<workspace-id-or-name>) - the URL itself selects the workspace.switchWorkspaceis rejected so the connector stays scoped. Add one connector per workspace if you want them listed separately in Claude or ChatGPT.
Permissions & Security
- Every MCP tool call runs as you within the currently active workspace
(the default, a later
switchWorkspacechoice, or the workspace pinned in the connector URL). - The agent only sees assets, tables, models, and jobs that your user role has permission to access in that workspace. It cannot switch to a workspace you did not authorize.
- All MCP tool executions and table reads are logged in Settings → Audit log
with origin
mcp.
Need a bearer key for the public REST API (
/api/public/v1/*) instead of
MCP? You can still generate personal API keys in Profile → API Keys for
the REST API.