MCP Plugin (@better-auth/mcp)#

Overview#

The MCP (Model Context Protocol) plugin enables a Better Auth instance to act as an OAuth 2.1 authorization server for MCP clients 1. Originally shipped inside better-auth on top of the deprecated oidc-provider plugin, serving OAuth endpoints under /mcp/* 1, MCP was extracted into its own standalone package as of v1.7.0-beta.6 2.

The new @better-auth/mcp is rebuilt on the maintained @better-auth/oauth-provider 3. The architectural boundary is clear: oauth-provider is the authorization server; MCP is the resource server that serves RFC 9728 protected resource metadata and verifies bearer tokens 1.

⚠️ The legacy mcp plugin still exists inside better-auth/plugins but is deprecated and will be removed. The current docs at better-auth.com/docs/plugins/mcp still reflect the old version 4.

Import Paths#

3

Public API Surface#

Server-side (@better-auth/mcp)#

• mcp(options) — main plugin. Configures the OAuth provider for MCP. Key option: resource (RFC 8707 resource identifier URI; defaults to the auth server's base URL) 3.
• requireMcpAuth(auth, handler, opts?) — route guard that validates the bearer token against JWKS and forwards verified JWT claims to the handler. Replaces old withMcpAuth 3.
• mcpHandler(verifyOptions, handler, opts?) — explicit token verifier for resource servers running separately from the auth server 3.

Token verification in the new package is JWT-claims-based (using JOSE + JWKS discovery), not session-record-based as in the old plugin 3.

Remote client (@better-auth/mcp/client)#

• createMcpResourceClient(options) — framework-agnostic client for resource servers that are separate processes/services. Returns: verifyToken, handler, discoveryHandler, protectedResourceHandler, middleware 3.

Framework adapters (@better-auth/mcp/client/adapters)#

• mcpAuthHono(options) — Hono middleware + discovery routes
• mcpAuthOfficial(options) — Official MCP SDK (@modelcontextprotocol/sdk) wrapper
• mcpAuthMcpUse(options) — drop-in mcp-use OAuth provider

3

Breaking Changes from Old Plugin#

3

After migrating, run npx auth migrate or npx auth generate to apply schema changes 3.

Legacy Plugin (Still in better-auth/plugins)#

The legacy plugin (pre-extraction) is documented at mcp.mdx and currently live on better-auth.com. Key legacy APIs:

• mcp({ loginPage, resource?, oidcConfig? }) — imported from better-auth/plugins
• withMcpAuth(auth, handler) — session-based route guard
• auth.api.getMcpSession({ headers }) — direct session lookup
• createMcpAuthClient({ authURL }) — remote client from better-auth/plugins/mcp/client
• oAuthDiscoveryMetadata(auth), oAuthProtectedResourceMetadata(auth) — helper route exports from better-auth/plugins
• Framework adapters: mcpAuthHono, mcpAuthOfficial, mcpAuthMcpUse from better-auth/plugins/mcp/client/adapters

The legacy session object includes accessToken, refreshToken, clientId, userId, scopes, and expiry fields 5.

Integration Patterns#

Same-process (legacy or new, co-located)#

Use withMcpAuth (legacy) or requireMcpAuth (new) directly with the auth instance when the MCP server and auth server share a process.

Separate resource server#

Use createMcpResourceClient pointed at the auth server's authURL. The client discovers JWKS via RFC 8414 metadata and verifies tokens locally — no database calls required. Mount discoveryHandler() and protectedResourceHandler(resourceUrl) at /.well-known/* paths on the MCP server 3 5.

Key Source Files#