JWT bearer (any OIDC issuer)
The foundation: verify a JWKS-signed access token with jose, map claims
to Principal, and honor the null-versus-throw hook contract.
Authentication recipes
Invokta ships no identity system. The MCP HTTP adapter accepts a pluggable
authenticate hook that turns a verified request identity into the minimal
Principal, and the core applies each capability’s access rule on every
channel. These recipes show where your existing provider plugs into that
boundary. Each one is backed by a runnable, offline-tested example in the
repository.
Choose a surface
Section titled “Choose a surface”| Callers reach the engine through | Use |
|---|---|
| MCP HTTP with bearer tokens from a hosted issuer | The JWT bearer recipe, then your provider’s recipe below |
| MCP HTTP from services and automations without a user | API keys |
| Your own application process that already resolved a session | The embedded pattern in the Auth.js and Better Auth recipes |
| An OAuth-capable MCP client that discovers your Authorization Server | MCP OAuth discovery |
| An MCP service that must operate its own users, login, consent, and tokens | Self-hosted OAuth |
Authentication proves who is calling and produces a Principal; whether that
principal may execute a capability stays a domain decision. Pair any recipe
here with domain authorization and the
HTTP authentication guide.
Provider recipes
Section titled “Provider recipes”Supabase
Verify Supabase Auth asymmetric JWTs against your project JWKS and map
sub, role, and session claims.
Clerk
Verify Clerk session tokens, enforce the authorized party, and map session and organization claims.
Auth0
Verify Auth0 API access tokens with a required audience and map scope and permission claims. Doubles as the template for Kinde, Logto, and other OIDC issuers.
AWS Cognito
Verify user-pool access tokens, validate client_id and token_use, and
map scopes and groups.
Firebase Auth
Keep firebase-admin behind a verifier port, wire verifyIdToken at the
composition root, and test the hook against a fake.
Better Auth
Verify JWTs issued by your own Better Auth app, or pass its resolved
session to engine.invoke when engine and app share a process.
Auth.js (NextAuth)
Lead with the embedded pattern from a route handler session, and issue an app-owned access token when callers must reach the engine over HTTP.
WorkOS AuthKit
Verify AuthKit access tokens and key multi-tenant access rules on the organization claims.
API keys
Authenticate services with hashed keys and constant-time comparison, and map each key to a service principal.
MCP OAuth discovery
Publish Protected Resource Metadata so OAuth-capable MCP clients discover your Authorization Server from the Bearer challenge.
Self-hosted OAuth for MCP
Import the production-oriented example with PostgreSQL, PKCE, DCR, login, consent, rotating refresh tokens, and Caddy or Traefik deployment assets.
Rules every recipe follows
Section titled “Rules every recipe follows”- The provider SDK or verification library stays at the composition root;
capabilities see only
Principal. - The hook returns a
Principalfor a valid credential,nullfor any invalid one, and throws only when verification infrastructure fails. - Principals carry verified, authorization-relevant claims — never the raw token, a full claim dump, or live SDK objects.
- Tests run offline: JWT recipes generate a local key pair and JWKS with
jose, so signature verification is real without any network.