OAuth authentication

Skillist acts as an OAuth provider for MCP clients. Cursor and other OAuth-aware clients can obtain Bearer tokens tied to your Skillist user.

Discovery URLs

MCP clients discover authorization metadata from the API origin:

Document	URL
Protected resource	https://api.skillist.io/.well-known/oauth-protected-resource
Authorization server	https://api.skillist.io/.well-known/oauth-authorization-server

Skillist also serves metadata under /api/auth/.well-known/… for clients that follow the auth server path.

Sign-in flow

1. Your MCP client reads WWW-Authenticate from an MCP response (or fetches protected-resource metadata).
2. The client opens the OAuth authorization URL.
3. You sign in at console.skillist.io/login (GitHub, Google, passkey, or magic link).
4. The client receives an access token and sends Authorization: Bearer <token> on subsequent MCP requests.

Public vs authenticated access

Access	Registry read tools
No token	Allowed — registry_search, registry_get_skill, registry_facets, registry_install_help
Bearer token	Same tools, session tied to your user ID for future authenticated tools

Registry MCP advertises OAuth via the WWW-Authenticate header on all responses so clients can upgrade to an authenticated session when needed.

Scopes

Default OIDC scopes: openid, profile, email, offline_access.

Local development

When running the API locally (http://localhost:8787):

Setting	Value
MCP endpoint	http://localhost:8787/mcp
Auth server	http://localhost:8787/api/auth
Login page	http://localhost:5174/login

Run pnpm dev:api and pnpm dev:console together for end-to-end OAuth testing.

Implementation notes

• OAuth tables: oauth_application, oauth_access_token, oauth_consent
• Token verification: GET /api/auth/mcp/get-session with Bearer token
• MCP transport: stateless streamable HTTP (protocol 2026-07-28) — no sessions; the Bearer token is verified on every request

For platform developers, see the API source under apps/api/src/mcp/ and packages/auth/.