MCP OAuth (desktop clients)

OpenBrain supports OAuth 2.1 authorization for MCP-capable AI apps (Claude Desktop, ChatGPT connectors, and other hosts that implement MCP OAuth) via Laravel Passport and laravel/mcp metadata routes.

Discovery

Endpoint	Purpose
GET /.well-known/oauth-authorization-server	Authorization server metadata
GET /.well-known/oauth-protected-resource	Protected resource metadata
POST /oauth/register	Dynamic client registration (RFC 7591)

MCP clients discover these automatically when /mcp returns 401 with a WWW-Authenticate header pointing at resource metadata.

User consent

1. User signs in to the OpenBrain dashboard at /app.
2. The authorization screen lists the requesting client, organization, and memory abilities (ingest, search, admin).
3. Approved tokens receive scopes: mcp:use, organization:{uuid}, and selected memory:* abilities.

Read-only members can only approve search scope.

Using OAuth tokens

• MCP: Authorization: Bearer {access_token} on POST /mcp (same tools as Sanctum PATs).
• REST: Authorization: Bearer {access_token} with optional X-Organization-Id when the token includes organization:{uuid}.

Configuration

In .env / config/mcp.php:

• custom_schemes: private URI schemes allowed for desktop OAuth callbacks (e.g. claude for Claude Desktop). Additional schemes may be added for other vendors.
• redirect_domains: restrict HTTPS callbacks in production (avoid *)

Run once per environment:

php artisan passport:install

Sanctum PATs

Long-lived personal access tokens created in the dashboard remain supported for automation and CI. Prefer OAuth for interactive desktop MCP sessions.