theAuthFastify(theauth, options?) returns an async Fastify plugin. Register it with fastify.register and use Fastify’s built-in prefix option to control the mount path.
Install
Setup
1
Create the theauth instance
2
Register the plugin
The prefix is controlled by Fastify’s
register options, and the handler picks it up. You can still pass basePath to override it.MCP endpoints
Whenmcp is passed, the MCP OAuth 2.1 endpoints are registered on the same plugin. Because Fastify’s prefix scopes routes, the well-known paths are served relative to the plugin root:
Management routes and client IP
With the default session guard, a signed-in user only acts on their own agents, delegations and audit rows. A customauthenticate resolver is a trust decision and sees everything.
The adapter does not read forwarded headers for the client IP. Behind a proxy, set trustedProxy with trustedProxyCount or trustedHeader, or ipAllowlist constraints cannot match.
trustedHeader: 'cf-connecting-ip'. Only trust a header your edge overwrites. Without trustedProxy the adapter uses request.ip, which is the socket peer unless your server framework is configured to trust the proxy.
Endpoint reference
Every adapter serves the same routes with the same status codes. See the route reference.Protect a route for agents
{ "error": { "code", "message" } }, where code is the decision code (for example no_permission). See the requireScope guide.
Full example
Related
Adapters overview
Compare all available framework adapters and their mount patterns.
Express
Router-based adapter for Express apps.
Hono
Lightweight adapter that runs on Workers, Bun, and Deno.
MCP
OAuth 2.1 authorization server endpoints mounted by the adapter.