Get started
Authentication
OAuth authorization code flow, PKCE, workspace grants and token lifecycle.
OAuth is implemented with Laravel Passport 13.7.6 and League OAuth2 Server. Only public authorization-code clients and refresh tokens are exposed. Client credentials, password grants, implicit grants, personal access tokens, and browser session cookies cannot authenticate MCP requests.
| Route | Purpose | Authentication |
|---|---|---|
GET /.well-known/oauth-protected-resource/mcp | Canonical resource, issuer and scopes | Public, MCP enabled |
GET /.well-known/oauth-protected-resource | Resource metadata alias | Public, MCP enabled |
GET /.well-known/oauth-authorization-server | Authorization/token/revocation/registration metadata | Public, MCP enabled |
POST /mcp/oauth/register | Register public client redirect URIs | Public, throttled |
GET /mcp/oauth/authorize | Sign in and display workspace/scope consent | Browser session |
POST /mcp/oauth/authorize | Approve or deny one-time consent | Browser session + CSRF |
POST /mcp/oauth/token | Exchange code or rotate refresh token | PKCE or refresh credential |
POST /mcp/oauth/revoke | Revoke the connection associated with a token | Possession of token + client ID |
POST /mcp | MCP protocol | OAuth bearer token |
GET /settings/integrations/mcp | Manage your connections and requests | Browser session |
POST /settings/integrations/mcp/connections/{uuid}/revoke | Revoke one connection | Browser session + CSRF |
GET/POST /settings/integrations/mcp/requests/{uuid} | Review/approve/decline an exact action | Owner session + CSRF for POST |
An unauthenticated MCP request returns HTTP 401 with a WWW-Authenticate: Bearer challenge containing resource_metadata. Register using the registration URL from issuer metadata. Registration accepts client_name, 1–10 redirect_uris, token_endpoint_auth_method: "none", authorization-code/refresh grant types, and response_types: ["code"]. Redirects must be HTTPS, or HTTP on loopback, with no fragment, user info or wildcard. HTTPS redirects and the localhost hostname use exact matching; numeric HTTP loopback ports follow RFC 8252.
Example public-client registration:
{
"client_name": "My Caroush agent",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"]
}The client creates a cryptographically random PKCE verifier and its SHA-256 base64url challenge, then opens the authorization endpoint with client_id, response_type=code, registered redirect_uri, resource equal to the exact MCP endpoint, requested space-separated scope, state, code_challenge, and code_challenge_method=S256. The user chooses the workspace. Clients cannot supply a user/workspace override to tools.
Exchange the code as form data with grant_type=authorization_code, client_id, redirect_uri, code, code_verifier and the same resource. Access tokens last one hour. Refresh tokens last 30 days and rotate after use. A refresh uses grant_type=refresh_token, client_id, refresh_token and resource; optional scope can narrow access, never expand it. Store tokens using your client's credential store and replace rotated refresh tokens immediately. Reusing a code or an old refresh token is rejected.
A workspace-specific grant marker is embedded by the server. The server verifies it against the signed token, recorded grant, client, resource, account status and current membership. Changing the browser's selected workspace cannot retarget a token. Revoke one grant in Settings or call revocation with token and client_id; existing codes, access tokens and refresh tokens for that grant are invalidated. Queued MCP operations recheck authorization and the MCP enabled flag before executing. Native publishing/generation work already started is not retroactively undone by revocation; stop it through the relevant Caroush workflow if needed.
Dynamic Client Registration is supported for compatibility. Client ID Metadata Documents are not implemented or advertised. Consent is not inferred from arbitrary website content. State, one-time consent nonces, session authentication and CSRF protect the browser authorization flow.