install

Install @brainwebuk/payload-plugin-mcp-oauth

Adds OAuth 2.1 + PKCE + Dynamic Client Registration to an existing @payloadcms/plugin-mcp MCP server. Additive — the API-key flow keeps working. Always prefer the latest version (the install path has had several fixes; use >= 0.3.3).

Prerequisites

• A Payload v3 app with @payloadcms/plugin-mcp already installed and working.
• Next.js 14 / 15 / 16 (for the exported proxy/middleware).

Steps

1. Install: pnpm add @brainwebuk/payload-plugin-mcp-oauth

2. Register it AFTER mcpPlugin(), sharing ONE options object (most common footgun):

   const mcpOptions = {
     collections: { posts: { enabled: { find: true, create: true, update: true } } },
   }
   plugins: [
     mcpPlugin(mcpOptions),
     payloadMcpOAuth({
       issuer: process.env.NEXT_PUBLIC_SERVER_URL!,
       mcpPluginOptions: mcpOptions, // ← the SAME reference, never a copy/spread
     }),
   ]
   

   A copy/spread silently breaks OAuth token auth (API keys keep working, so it's easy to miss). Registering it before mcpPlugin() throws on boot.

3. Add the proxy — Next 16: src/proxy.ts; Next 14/15: src/middleware.ts. Re-export the handler but declare config as a local literal (never re-export config — it 500s every route on Next 16):

   export { mcpOAuthMiddleware as proxy } from '@brainwebuk/payload-plugin-mcp-oauth/middleware'
   export const config = {
     matcher: ['/', '/.well-known/oauth-authorization-server', '/.well-known/oauth-protected-resource'],
   }
   

4. Env: set NEXT_PUBLIC_SERVER_URL (public HTTPS origin; used as the OAuth issuer) and PMOAUTH_TOKEN_PEPPER (openssl rand -hex 32; required ≥ 32 chars in production). Ensure Payload's serverURL equals NEXT_PUBLIC_SERVER_URL — the consent flow relies on a first-party session cookie matching that origin.

5. Apply the schema — pick ONE workflow, don't mix:

   • Dev push (SQLite/Postgres in dev): just start the app.
   • Migrations (production): pnpm payload migrate:create then pnpm payload migrate. If you already booted the app once before installing, on SQLite either upgrade to >= 0.3.2 or reset the dev DB (rm your.db*) so the schema is created fresh.