MCP Authentication
Use OAuth client credentials to authenticate server-side MCP agents.
MCP Authentication
MCP only accepts Better Auth OAuth access tokens issued to confidential Customer-backend agents. Do not use API keys, personal access tokens, browser sessions, or public client credentials with the MCP endpoint.
The MCP endpoint advertises OAuth Protected Resource Metadata at https://mcp.builtlms.com/.well-known/oauth-protected-resource/mcp. Unauthorized MCP requests include a WWW-Authenticate header pointing clients to that metadata document.
Provision An Agent
A tenant admin creates an MCP agent from the admin API surface. The response returns the client secret once.
POST /api/admin/mcp/agents
Content-Type: application/json
{
"name": "HRIS Sync",
"description": "Nightly learner and enrollment automation",
"scopes": ["users:read", "users:write", "enrollments:read", "enrollments:write"]
}Store the returned clientSecret in your backend secret manager. It cannot be read again; rotate it if it is lost or exposed.
Request A Token
Use the OAuth client-credentials grant from a server-side process.
curl -sS https://app.builtlms.com/api/oauth/token \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=$BUILT_LMS_MCP_CLIENT_ID' \
-d 'client_secret=$BUILT_LMS_MCP_CLIENT_SECRET' \
-d 'scope=users:read enrollments:read'The access token must include:
aud:https://mcp.builtlms.com/mcporganization_id: the tenant organization UUIDclient_id: the MCP OAuth client idscope: space-delimited MCP scopes
Tokens are short-lived. Cache them in your backend until expiry, then request a new token with the same client credentials.
Rotate Or Revoke
POST /api/admin/mcp/agents/{id}/rotate-secret
DELETE /api/admin/mcp/agents/{id}Rotation returns a new one-time clientSecret. Revocation disables the MCP OAuth client without changing existing user accounts.