OAuth 2.1

The Opelyx MCP server supports OAuth 2.1 for interactive clients that implement the authorization code flow. This is an alternative to Bearer token (API key) authentication.

Discovery

The MCP server publishes its resource metadata at the standard RFC 9728 endpoint:

curl https://mcp.opelyx.com/.well-known/oauth-protected-resource

{
  "resource": "https://mcp.opelyx.com",
  "authorization_servers": ["https://auth.opelyx.com"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "bearer_methods_supported": ["header"],
  "resource_signing_alg_values_supported": ["RS256"]
}

This tells the client to use auth.opelyx.com as the authorization server and what scopes are available.

Authorization Flow

Client discovers the authorization server via /.well-known/oauth-protected-resource
Client initiates authorization by redirecting the user to auth.opelyx.com with the required OAuth parameters
User authenticates at auth.opelyx.com (login or sign up)
Authorization code is exchanged for access and refresh tokens
Access token is used as a Bearer token in MCP requests
Refresh tokens are used to obtain new access tokens when they expire

Token Usage

OAuth access tokens are used exactly like API keys — in the Authorization header:

Authorization: Bearer <access_token>

The MCP server validates the token against the oauth_access_token table in the auth database, checking expiration and extracting the user’s subscription tier.

Session Lifecycle

MCP connections use Durable Objects with a 30-minute inactivity timeout:

Each new connection starts or resumes a DO session
Activity (tool calls) resets the inactivity timer
After 30 minutes of inactivity, the session is destroyed
The client reconnects and creates a new session automatically

Rate Limiting

OAuth-authenticated requests use the same tier-based rate limits as API key requests. The rate limit key is based on the user ID (not the token), so token rotation does not reset the daily counter.

Tier	Daily Limit
Free	100
Pro	10,000
Enterprise	100,000