Skip to main content
The Less MCP server uses OAuth 2.1 (@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 to https://<your-workspace-host>/api/mcp without a token:
  1. Challenge (401 Unauthorized) - Less returns an RFC 9728 WWW-Authenticate header pointing to /.well-known/oauth-protected-resource.
  2. Metadata Discovery - The client fetches Protected Resource Metadata (/.well-known/oauth-protected-resource) and Authorization Server Metadata (/.well-known/oauth-authorization-server).
  3. Client Identification - Clients identify themselves either via Client ID Metadata Documents (CIMD) (mcp-2026-07-28) or Dynamic Client Registration (/api/auth/oauth2/register).
  4. 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.
  5. 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_id is the default; allowed_subscription_ids is the full set), verified via /api/auth/jwks.

Multiple workspaces

  • Single connector (/api/mcp) - authorize several workspaces on the consent screen. The agent uses listWorkspaces / switchWorkspace to move between them. switchWorkspace is remembered for that user + MCP client.
  • Pinned connector (/api/mcp/<workspace-id-or-name>) - the URL itself selects the workspace. switchWorkspace is 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 switchWorkspace choice, 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.