AI Connector (MCP)
OAuth Reference
OAuth 2.1 endpoints for MCP connector authentication.
Recurex implements a custom OAuth 2.1 authorization server for MCP clients.
Discovery endpoints
| Endpoint | Standard |
|---|---|
GET /.well-known/oauth-authorization-server | RFC 8414 |
GET /.well-known/oauth-protected-resource | RFC 9728 |
GET /api/mcp/.well-known/oauth-protected-resource | RFC 9728 (MCP path) |
Protected resource metadata points to authorization servers and supported scope expenses:rw.
Authorization
GET /api/oauth/authorize
| Param | Required | Notes |
|---|---|---|
client_id | Yes | DCR client ID or CIMD URL |
redirect_uri | Yes | Must match registration |
code_challenge | Yes | S256 PKCE |
code_challenge_method | No | Must be S256 |
state | No | CSRF protection |
resource | No | Defaults to MCP resource URL |
Unauthenticated users redirect to /login?next=.... Authenticated users see an HTML consent page.
POST with action=approve|deny completes the flow. Approval issues an HMAC-signed authorization code (10 min TTL) bound to user, org, PKCE challenge, and resource.
Token exchange
POST /api/oauth/token
Authorization code grant
| Param | Required |
|---|---|
grant_type | authorization_code |
code | Yes |
code_verifier | Yes |
redirect_uri | Yes |
client_id | Yes |
resource | Validated if present |
Response:
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "expenses:rw"
}Refresh token grant
Rotating refresh — old token revoked, new pair issued. Refresh tokens last 30 days.
Dynamic client registration
POST /api/oauth/register
RFC 7591. Body: { "redirect_uris": ["..."], "client_name": "..." }. Returns client_id.
Token storage
Access and refresh tokens are hashed in mcp_tokens. Authorization codes are single-use with replay prevention via oauth_used_codes.
Environment variables
| Variable | Purpose |
|---|---|
OAUTH_CODE_SECRET | HMAC signing for auth codes |
NEXT_PUBLIC_SITE_URL | Resource URL and redirects |
SUPABASE_SERVICE_ROLE_KEY | Token persistence |
MCP authentication
Authorization: Bearer <access_token>
Validated by lib/mcp-auth.ts: non-revoked, non-expired token; user still a member of token's org; plan includes ai:connector.