MCP
OAuth Flow
How the MCP OAuth bridge works for self-serve ChatGPT and Claude connections.
When AIDELLY_MCP_AUTH_MODE=oauth, the MCP server acts as an OAuth authorization server, letting end users sign into their own Aidelly account rather than sharing a single API key.
Auth modes
| Mode | Behavior |
|---|---|
optional | Accepts Authorization: Bearer <key> and x-aidelly-api-key. Useful for dev/testing. |
required | Same as optional but authentication is expected for production traffic. |
oauth | Bearer-only. Rejects x-aidelly-api-key and server-side default key fallback. Recommended for public ChatGPT/Claude self-serve. |
OAuth endpoints
GET /api/mcp/oauth/authorize ← Authorization page (user signs in here)
POST /api/mcp/oauth/token ← Token exchange
GET /api/mcp/.well-known/oauth-authorization-server
GET /api/mcp/.well-known/oauth-protected-resourceAll endpoints are also available under the /mcp/... alias.
Authorization flow
Client (ChatGPT / Claude.ai)
│
│ 1. Redirect to /api/mcp/oauth/authorize?client_id=...&redirect_uri=...
▼
Aidelly OAuth page (user signs in)
│
│ 2. Issue authorization code
▼
Client callback URL
│
│ 3. POST /api/mcp/oauth/token { code, client_id, redirect_uri }
▼
Aidelly issues access token (scoped API key, 30-day TTL)
│
│ 4. Client uses Bearer token for all tool calls
▼
MCP tools run as that Aidelly userToken details
- Access tokens are scoped per-user Aidelly API keys
- Default TTL: 30 days (
2592000seconds) - Authorization codes expire in 10 minutes (
600seconds) - Tokens can be revoked from Settings → API Keys in the Aidelly dashboard
Discovery request
MCP clients probe the server before initiating auth:
curl https://app.aidelly.ai/api/mcp/.well-known/oauth-authorization-server{
"issuer": "https://app.aidelly.ai",
"authorization_endpoint": "https://app.aidelly.ai/api/mcp/oauth/authorize",
"token_endpoint": "https://app.aidelly.ai/api/mcp/oauth/token",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code"]
}initialize without auth
initialize can run without authentication (for discovery). tools/list can also run without auth unless AIDELLY_MCP_REQUIRE_AUTH_FOR_DISCOVERY=true is set — leaving it false is recommended so ChatGPT and Claude can discover tools during connector setup.
All tools/call requests always require authentication.