OAuth reference

Lucent’s MCP endpoint is fronted by an OAuth 2.1 authorization server that conforms to the MCP specification. For the user-facing setup walkthrough, see the quickstart. This page documents the protocol surface for client implementers.

Discovery

Both metadata documents are publicly readable and CORS-open.

Protected resource metadata

GET https://app.lucenthq.com/.well-known/oauth-protected-resource Returns the resource server’s identity and which authorization servers issue tokens for it.

{
  "resource": "https://app.lucenthq.com/api/mcp",
  "authorization_servers": ["https://app.lucenthq.com"],
  "scopes_supported": ["read:lucent"]
}

Authorization server metadata

GET https://app.lucenthq.com/.well-known/oauth-authorization-server Returns the endpoints, supported parameters, and capabilities.

{
  "issuer": "https://app.lucenthq.com",
  "authorization_endpoint": "https://app.lucenthq.com/oauth/authorize",
  "token_endpoint": "https://app.lucenthq.com/api/oauth/token",
  "registration_endpoint": "https://app.lucenthq.com/api/oauth/register",
  "revocation_endpoint": "https://app.lucenthq.com/api/oauth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post"],
  "revocation_endpoint_auth_methods_supported": ["none", "client_secret_post"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["read:lucent"]
}

The only supported grant flow is authorization code with PKCE (S256). Implicit, password, and client_credentials are not supported. plain PKCE is rejected.

Dynamic Client Registration

POST https://app.lucenthq.com/api/oauth/register Implements RFC 7591. Rate-limited per IP — busy clients should cache the resulting client_id rather than re-register. Request

{
  "client_name": "Acme Connector",
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read:lucent"
}

Field	Required	Notes
`redirect_uris`	yes	At least one. Each must be in the allowlist. HTTPS or loopback only.
`client_name`	no	≤ 64 chars; letters, numbers, spaces, `-_.()`. Defaults to `Unnamed Client`.
`token_endpoint_auth_method`	no	`none` (public client + PKCE, default) or `client_secret_post`.
`grant_types`	no	Subset of `["authorization_code", "refresh_token"]`. Defaults to both.
`response_types`	no	Must include `code`. Defaults to `["code"]`.
`scope`	no	Defaults to `read:lucent`.

Response (201 Created)

{
  "client_id": "luc_client_…",
  "client_secret": "…",
  "client_name": "Acme Connector",
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read:lucent"
}

client_secret is only present when token_endpoint_auth_method is client_secret_post. Public clients (the default for native MCP clients) get client_id only and authenticate with PKCE.

Allowed redirect URIs

The redirect allowlist defends against open-redirect and auth-code injection. Registration rejects URIs outside this list with an InvalidClientMetadataError and an opaque message.

Type	Allowed values
Hosted (HTTPS)	`https://claude.ai`, `https://claude.com`
Loopback (HTTP)	`http://127.0.0.1`, `http://[::1]`, `http://localhost` — any port and path

URIs with embedded credentials (https://user:pass@…) or fragments (#…) are rejected per RFC 6749 §3.1.2. To add another hosted origin, email [email protected].

Authorization request

GET https://app.lucenthq.com/oauth/authorize?… Standard OAuth 2.1 authorization-code request with PKCE:

Param	Required	Notes
`response_type`	yes	Must be `code`.
`client_id`	yes	From registration.
`redirect_uri`	yes	Must exactly match one of the registered `redirect_uris`.
`code_challenge`	yes	43–128 chars, base64url-encoded SHA-256 of the verifier.
`code_challenge_method`	yes	Must be `S256`.
`state`	rec.	Opaque value the client uses for CSRF protection.
`scope`	no	Defaults to `read:lucent`.

If the user isn’t signed in to Lucent, they’re routed through /login and returned to the consent screen after authentication. If a consent record already exists for this (client_id, scope) and hasn’t been revoked, the consent screen is bypassed and the browser is redirected back to redirect_uri with ?code=…&state=… immediately. If anything is wrong (unknown client, revoked client, redirect_uri mismatch, malformed PKCE), the user sees a single opaque error page — no detail is leaked that would let an unauthenticated probe enumerate client state.

Token endpoint

POST https://app.lucenthq.com/api/oauth/token Content-Type: application/x-www-form-urlencoded. Returns Cache-Control: no-store.

`grant_type=authorization_code`

POST /api/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=luc_oac_…
&redirect_uri=https://claude.ai/api/mcp/auth_callback
&client_id=luc_client_…
&code_verifier=…
&client_secret=…   (only if token_endpoint_auth_method=client_secret_post)

The redirect_uri must match the value sent at authorize time (RFC 6749 §4.1.3 / OAuth 2.1 §4.1.3). Codes are single-use and expire after 60 seconds. Reuse of an already-redeemed code revokes any tokens previously issued from it.

`grant_type=refresh_token`

grant_type=refresh_token
&refresh_token=luc_ort_…
&client_id=luc_client_…
&scope=read:lucent          (optional, must be ⊆ originally granted)
&client_secret=…            (only if confidential client)

Refresh tokens rotate on every exchange — the old refresh token is marked rotated and a new pair is returned. If a rotated refresh token is presented again, the entire token chain (access + refresh) for that session is revoked as a reuse-detection cascade.

Response

{
  "access_token": "luc_oat_…",
  "refresh_token": "luc_ort_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:lucent"
}

TTL	Default	Env var
Access token	1 hour	`OAUTH_ACCESS_TOKEN_TTL_SECONDS`
Refresh token	30 days	`OAUTH_REFRESH_TOKEN_TTL_DAYS`
Authorization code	60 seconds	`OAUTH_AUTHORIZATION_CODE_TTL_SECONDS`

Revocation endpoint

POST https://app.lucenthq.com/api/oauth/revoke Implements RFC 7009 and is idempotent — always returns 200 even for unknown tokens.

POST /api/oauth/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded

token=luc_oat_… or luc_ort_…
&token_type_hint=access_token | refresh_token   (optional)
&client_id=luc_client_…
&client_secret=…   (only if confidential client)

Use this when a user signs out of your client. Lucent also exposes a Connected apps section in the dashboard so end users can unilaterally revoke any registered client.

Tools and scopes

Every token currently carries the single read:lucent scope. The four read-only tools (list_signals, list_issues, get_issue, list_insights) are gated behind that scope at the MCP handler level via withMcpAuth({ requiredScopes: ["read:lucent"] }). See the tool reference for arguments and return shapes.

Errors

OAuth-protocol errors follow the RFC 6749 §5.2 JSON shape:

{ "error": "invalid_grant", "error_description": "PKCE verification failed" }

User-visible authorize-page failures collapse to a single opaque message. Token-endpoint client-auth failures are also opaque (no distinction between “unknown client_id” and “wrong secret”) — both defenses are deliberate and prevent enumeration of registered clients.

Get started

Browser SDK

MCP

AI tools

OAuth reference

Discovery

Protected resource metadata

Authorization server metadata

Dynamic Client Registration

Allowed redirect URIs

Authorization request

Token endpoint

`grant_type=authorization_code`

`grant_type=refresh_token`

Response

Revocation endpoint

Tools and scopes

Errors

Get started

Browser SDK

MCP

AI tools

Documentation Index

​Discovery

​Protected resource metadata

​Authorization server metadata

​Dynamic Client Registration

​Allowed redirect URIs

​Authorization request

​Token endpoint

​grant_type=authorization_code

​grant_type=refresh_token

​Response

​Revocation endpoint

​Tools and scopes

​Errors

Discovery

Protected resource metadata

Authorization server metadata

Dynamic Client Registration

Allowed redirect URIs

Authorization request

Token endpoint

`grant_type=authorization_code`

`grant_type=refresh_token`

Response

Revocation endpoint

Tools and scopes

Errors