OAuth for MCP Clients

Quickstart

1. Discover the authorization server through /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.
2. Register your client by POSTing to /oauth/register (RFC 7591). No authentication is required. The endpoint issues a public client id.
3. Run the OAuth 2.1 authorization-code flow with PKCE S256. The user signs in to StremAI and approves a whole-account grant covering every project and memory.
4. Exchange the code at /oauth/token with your code_verifier and send the returned bearer token to /api/mcp.

Discovery

StremAI publishes two standard discovery documents:

• /.well-known/oauth-authorization-server returns the OAuth 2.1 metadata, including the authorization_endpoint, token_endpoint, registration_endpoint, supported scopes, and code_challenge_methods_supported (PKCE S256).
• /.well-known/oauth-protected-resource (RFC 9728) describes /api/mcp as the protected resource and points back at the StremAI authorization server. MCP clients use this to discover where to authenticate.

Dynamic Client Registration

POST your client metadata to /oauth/register. The endpoint is unauthenticated and issues a public client (PKCE is the security mechanism, no client secret is returned). DCR is the default path for MCP clients. The dashboard registration path exists only for clients that need a named, owner-attached identity.

POST /oauth/register
Content-Type: application/json

{
  "redirect_uris": ["https://client.example/callback"],
  "client_name": "Example MCP Client",
  "scope": "read write"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "client_id": "abk_...",
  "client_id_issued_at": 1717286400,
  "redirect_uris": ["https://client.example/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "client_name": "Example MCP Client",
  "scope": "read write"
}

Only read and write are self-grantable through DCR; admin is never issued through the unauthenticated endpoint. Requested scopes that StremAI does not support are dropped, not rejected.

Authorization Request

Redirect the user to /oauth/authorize with PKCE S256. See RFC 7636 for the PKCE specification.

https://www.aiagentsbay.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fclient.example%2Fcallback&code_challenge=PKCE_CHALLENGE&code_challenge_method=S256&scope=read%20write&state=STATE

The user signs in to StremAI, approves the named client, and is redirected back with an authorization code. Consent covers the user's whole account brain. Roles are checked per project on every request, so a grant never gives a client more access than the user already has.

Token Exchange

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

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https://client.example/callback
&code_verifier=PKCE_VERIFIER

Public clients send code_verifier and omit client_secret. Access tokens are short-lived bearer tokens with a one-hour default expiration. The client re-runs the authorization flow when a token expires.

Scopes

Revocation and Introspection

A dashboard owner can revoke a client or an individual grant. Clients can also call /oauth/revoke. Introspection at /oauth/introspect returns { active: false } for revoked grants.