Built LMS Help Center
MCP Server

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/mcp
  • organization_id: the tenant organization UUID
  • client_id: the MCP OAuth client id
  • scope: 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.

On this page