Skip to main content
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

When mcp 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:
All MCP routes include CORS headers and respond to OPTIONS preflight requests.

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 custom authenticate 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.
On Cloudflare use 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

Missing or invalid bearer token returns 401 and a denied scope returns 403. The body is { "error": { "code", "message" } }, where code is the decision code (for example no_permission). See the requireScope guide.

Full example

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.
Last modified on October 18, 2026