@payloadcms/plugin-mcp 4.0.0-internal.77191e5 → 4.0.0-internal.7d5c665

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-internal.77191e5",
+  "version": "4.0.0-internal.7d5c665",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
     "plugin",
@@ -55,15 +55,15 @@
     "bin.js"
   ],
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
-    "tsx": "4.22.4"
+    "@modelcontextprotocol/server": "2.3.1",
+    "tsx": "4.23.15"
   },
   "devDependencies": {
     "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-internal.77191e5"
+    "payload": "4.0.0-internal.7d5c665"
   },
   "peerDependencies": {
-    "payload": "4.0.0-internal.77191e5"
+    "payload": "4.0.0-internal.7d5c665"
   },
   "//deps_notes": {
     "tsx": "Required by the `bin.js` stdio mcp. Keep the version pinned to whatever `payload` ships to avoid duplicate installs."

package/src/endpoint/access.ts

@@ -1,6 +1,6 @@
 import type { PayloadRequest, SanitizedPermissions } from 'payload'
 
-import { getAccessResults, UnauthorizedError } from 'payload'
+import { executeAuthStrategies, getAccessResults, UnauthorizedError } from 'payload'
 
 import type { AuthorizedMCP, MCPItem } from '../types.js'
 
@@ -34,9 +34,18 @@ export const getAuthorizedMCP: (args: GetAuthorizedMCPArgs) => Promise<Authorize
     const hasAuthorization = headers.has('Authorization')
 
     headers.set('DisableAutologin', 'true')
-    req.user = (await req.payload.auth({ headers, req })).user
+    // Not `payload.auth()`, which also computes permissions that filterMCPItems computes anyway
+    req.user = (await executeAuthStrategies({ headers, payload: req.payload, req })).user
+
+    // Only bearer tokens that no auth strategy accepted reach the hook, e.g. an OAuth access token.
+    // API keys use the `<collection> API-Key <key>` scheme instead of `Bearer`, so they never do.
+    const bearerToken = headers.get('Authorization')?.match(/^Bearer (.+)$/)?.[1]
+    if (!req.user && bearerToken && pluginConfig.oauth?.authenticate) {
+      req.user = await pluginConfig.oauth.authenticate({ req, token: bearerToken })
+    }
 
-    if (hasAuthorization && !req.user) {
+    // With OAuth, the endpoint answers with a challenge that starts the client's sign-in
+    if (hasAuthorization && !req.user && !pluginConfig.oauth) {
       throw new UnauthorizedError(req.t)
     }
   }

package/src/endpoint/index.ts

@@ -3,6 +3,7 @@ import type { PayloadHandler, PayloadRequest } from 'payload'
 import {
   createMcpHandler,
   isLegacyRequest,
+  readRequestBody,
   WebStandardStreamableHTTPServerTransport,
 } from '@modelcontextprotocol/server'
 import { APIError } from 'payload'
@@ -10,6 +11,7 @@ import { APIError } from 'payload'
 import { buildMcpServer } from '../mcp/buildMcpServer.js'
 import { getPluginConfig } from '../utils/getPluginConfig.js'
 import { getAuthorizedMCP } from './access.js'
+import { getMCPResource, oauthChallenge } from './oauth.js'
 
 export const mcpEndpoint: PayloadHandler = async (req) => {
   if (!req.url) {
@@ -17,6 +19,8 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   }
 
   req.payloadAPI = 'MCP' as const
+  // Lets auth strategies check that an OAuth access token was issued for this MCP server
+  req.context.mcp = { resource: getMCPResource({ config: req.payload.config, url: req.url }) }
 
   const pluginConfig = getPluginConfig({ config: req.payload.config })
   const overrideAccessParam = new URL(req.url).searchParams.get('overrideAccess')
@@ -33,14 +37,22 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   }
 
   const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+
+  if (pluginConfig.oauth && !req.user) {
+    return oauthChallenge({ req })
+  }
+
+  const maxRequestBodySize = pluginConfig.mcp?.maxRequestBodySize
   // Payload augments the original web-standard Request in place.
   const mcpRequest = req as PayloadRequest & Request
+  const parsedBody = await parseRequestBody({ maxRequestBodySize, request: mcpRequest })
 
   // Keep the old JSON-only, stateless behavior because the SDK's 2025 fallback uses SSE.
-  if (await isLegacyRequest(mcpRequest)) {
+  if (await isLegacyRequest(mcpRequest, parsedBody, { maxRequestBodySize })) {
     const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
     const transport = new WebStandardStreamableHTTPServerTransport({
       enableJsonResponse: true,
+      maxRequestBodySize,
       sessionIdGenerator: undefined, // stateless mode
     })
     transport.onerror = (err) => {
@@ -49,7 +61,7 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
 
     try {
       await server.connect(transport)
-      return await transport.handleRequest(mcpRequest)
+      return await transport.handleRequest(mcpRequest, { parsedBody })
     } finally {
       await server.close().catch((err) => {
         req.payload.logger.error({ err, msg: 'Error closing MCP server' })
@@ -59,6 +71,7 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
 
   const handler = createMcpHandler(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {
     legacy: 'reject',
+    maxRequestBodySize,
     // SDK subscriptions always use SSE, so disable them to keep every response JSON-only.
     maxSubscriptions: 0,
     onerror: (err) => {
@@ -68,10 +81,35 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   })
 
   try {
-    return await handler.fetch(mcpRequest)
+    return await handler.fetch(mcpRequest, { parsedBody })
   } finally {
     await handler.close().catch((err) => {
       req.payload.logger.error({ err, msg: 'Error closing modern MCP handler' })
     })
   }
 }
+
+/**
+ * Parses a POST body once so the era check and the SDK handler can share it. The SDK
+ * skips its size limit for a pre-parsed body, so this reads with the same limit. It reads
+ * a clone and returns `undefined` for any body the SDK should reject (too large, unreadable,
+ * or not JSON), leaving the original request for the SDK to read and answer.
+ */
+const parseRequestBody = async ({
+  maxRequestBodySize,
+  request,
+}: {
+  maxRequestBodySize?: number
+  request: Request
+}): Promise<unknown> => {
+  if (request.method.toUpperCase() !== 'POST') {
+    return undefined
+  }
+
+  try {
+    const body = await readRequestBody(request.clone(), maxRequestBodySize)
+    return body.tooLarge ? undefined : JSON.parse(body.text)
+  } catch {
+    return undefined
+  }
+}

package/src/endpoint/oauth.ts

@@ -0,0 +1,87 @@
+import type { OAuthProtectedResourceMetadata } from '@modelcontextprotocol/server'
+import type { PayloadHandler, PayloadRequest, SanitizedConfig } from 'payload'
+
+import {
+  bearerAuthChallengeResponse,
+  OAuthError,
+  OAuthErrorCode,
+} from '@modelcontextprotocol/server'
+
+import { getPluginConfig } from '../utils/getPluginConfig.js'
+
+/**
+ * Serves the OAuth protected resource metadata (RFC 9728) at `/api/mcp/oauth-protected-resource`.
+ * The OAuth challenge links here, so MCP clients find the authorization server without setup.
+ */
+export const oauthProtectedResourceEndpoint: PayloadHandler = (req) =>
+  getMetadataResponse({ config: req.payload.config, url: req.url! })
+
+/**
+ * Serves the same metadata for clients that ignore the challenge's link and only look at
+ * `/.well-known/oauth-protected-resource`. Mount it at the site root, e.g. in Next.js at
+ * `app/.well-known/oauth-protected-resource/[[...path]]/route.ts`:
+ *
+ * ```ts
+ * import config from '@payload-config'
+ * import { oauthProtectedResourceHandler } from '@payloadcms/plugin-mcp'
+ *
+ * export const GET = oauthProtectedResourceHandler(config)
+ * ```
+ */
+export const oauthProtectedResourceHandler =
+  (config: Promise<SanitizedConfig> | SanitizedConfig) =>
+  async (request: Request): Promise<Response> =>
+    getMetadataResponse({ config: await config, url: request.url })
+
+/**
+ * Answers an unauthenticated MCP request with a challenge linking to the protected resource
+ * metadata, which starts the client's OAuth flow.
+ */
+export const oauthChallenge = ({ req }: { req: PayloadRequest }): Response =>
+  bearerAuthChallengeResponse(
+    new OAuthError(OAuthErrorCode.InvalidToken, req.t('error:unauthorized')),
+    {
+      requiredScopes: getPluginConfig({ config: req.payload.config }).oauth?.scopes,
+      resourceMetadataUrl: `${getMCPURL({ config: req.payload.config, url: req.url! })}/oauth-protected-resource`,
+    },
+  )
+
+/**
+ * The MCP endpoint's address, as advertised in the metadata's `resource`. Clients send it when
+ * they sign in, and authorization servers that support it put it in the access token's audience.
+ */
+export const getMCPResource = ({ config, url }: { config: SanitizedConfig; url: string }): string =>
+  getPluginConfig({ config }).oauth?.resource ?? getMCPURL({ config, url })
+
+const getMCPURL = ({ config, url }: { config: SanitizedConfig; url: string }): string =>
+  new URL(`${config.routes.api}/mcp`, config.serverURL || url).href
+
+const getMetadataResponse = async ({
+  config,
+  url,
+}: {
+  config: SanitizedConfig
+  url: string
+}): Promise<Response> => {
+  const pluginConfig = getPluginConfig({ config })
+
+  if (!pluginConfig.oauth) {
+    return new Response(null, { status: 404 })
+  }
+
+  const { authorizationServers, scopes } = pluginConfig.oauth
+
+  return Response.json(
+    {
+      authorization_servers:
+        typeof authorizationServers === 'function'
+          ? await authorizationServers()
+          : authorizationServers,
+      bearer_methods_supported: ['header'],
+      resource: getMCPResource({ config, url }),
+      scopes_supported: scopes,
+    } satisfies OAuthProtectedResourceMetadata,
+    // Public document, readable by browser-based MCP clients on any origin
+    { headers: { 'Access-Control-Allow-Origin': '*' } },
+  )
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import { definePlugin } from 'payload'
 import type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig } from './types.js'
 
 import { mcpEndpoint } from './endpoint/index.js'
+import { oauthProtectedResourceEndpoint } from './endpoint/oauth.js'
 import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
 
 declare module 'payload' {
@@ -13,11 +14,19 @@ declare module 'payload' {
     /** After the plugin's `plugin` callback runs, `options` holds the sanitized config. */
     '@payloadcms/plugin-mcp': MCPPluginConfig
   }
+  export interface RequestContext {
+    /** Set on MCP requests before they're authenticated. */
+    mcp?: {
+      /** The MCP endpoint's address, which OAuth access tokens for MCP are issued for. */
+      resource: string
+    }
+  }
 }
 
 export type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig }
 
 export { defineCollectionTool, defineGlobalTool, definePrompt, defineTool } from './defineTool.js'
+export { oauthProtectedResourceHandler } from './endpoint/oauth.js'
 
 export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
@@ -40,15 +49,23 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
       ...config,
       endpoints: [
         ...(config.endpoints ?? []),
-        // Payload prefixes /api, so the full path is /api/mcp.
-        { handler: mcpEndpoint, method: 'post', path: '/mcp' },
+        // Payload prefixes /api, so the full path is /api/mcp. getAuthorizedMCP authenticates the
+        // request with dev auto-login turned off, so Payload doesn't authenticate it first.
+        { disableAuth: true, handler: mcpEndpoint, method: 'post', path: '/mcp' },
         // Streamable HTTP's optional server=>client GET stream. We don't offer
         // one, so answer 405 per spec-— clients then skip it cleanly
         {
+          disableAuth: true,
           handler: () => new Response(null, { headers: { Allow: 'POST' }, status: 405 }),
           method: 'get',
           path: '/mcp',
         },
+        {
+          disableAuth: true,
+          handler: oauthProtectedResourceEndpoint,
+          method: 'get',
+          path: '/mcp/oauth-protected-resource',
+        },
       ],
     }
   },

package/src/mcp/buildMcpServer.ts

@@ -25,7 +25,7 @@ import { toStandardSchema } from '../utils/toStandardSchema.js'
  *
  * `req` is the request context handlers see. For HTTP it's the live
  * `PayloadRequest` derived from the incoming HTTP request; for stdio it's a
- * synthesized one built via `createLocalReq`.
+ * synthesized one built via `createPayloadRequest`.
  */
 export const buildMcpServer = ({
   authorizedMCP,

package/src/mcp/builtin/collections/authTools.ts

@@ -1,4 +1,4 @@
-import { createLocalReq, strictObject, z } from 'payload'
+import { createPayloadRequest, strictObject, z } from 'payload'
 
 import type { MCPToolResponse } from '../../../types.js'
 
@@ -53,7 +53,10 @@ export const authCollectionTool = defineCollectionTool({
     if (input.headers) {
       authHeaders = new Headers(input.headers)
     }
-    const authReq = await createLocalReq({ req: { headers: authHeaders } }, req.payload)
+    const authReq = await createPayloadRequest({
+      payload: req.payload,
+      req: { headers: authHeaders },
+    })
     const result = await req.payload.auth({ headers: authHeaders, req: authReq })
 
     if (result.user) {

package/src/mcp/builtin/collections/getCollectionSchemaTool.ts

@@ -1,4 +1,5 @@
 import { getAccessResults, getCollectionInputSchema, getCollectionSchemaInputSchema } from 'payload'
+import { getLLMInstructions } from 'payload/internal'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
@@ -16,7 +17,8 @@ export const getCollectionSchemaTool = defineCollectionTool({
     readOnlyHint: true,
     title: 'Get Collection Schema',
   },
-  description: 'Get the input schema for creating or updating documents in a collection.',
+  description:
+    'Get the input schema and LLM instructions before creating or updating documents in a collection.',
   input: getCollectionSchemaInputSchema,
 }).handler(async ({ slug, authorizedMCP, req }) => {
   const permissions = authorizedMCP.overrideAccess
@@ -64,17 +66,26 @@ export const getCollectionSchemaTool = defineCollectionTool({
       }
     : { enabled: false }
 
+  const instructions = await getLLMInstructions({
+    slug,
+    type: 'collection',
+    overrideAccess: authorizedMCP.overrideAccess,
+    req,
+  })
+
   return {
     content: [
       {
         type: 'text',
         text: `Schema for collection "${slug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\`\nUpload configuration:\n\`\`\`json\n${JSON.stringify(upload)}\n\`\`\``,
       },
+      ...(instructions ? [{ type: 'text' as const, text: instructions }] : []),
     ],
     structuredContent: {
       slug,
       schema: inputSchema,
       upload,
+      ...(instructions ? { instructions } : {}),
     },
   }
 })

package/src/mcp/builtin/globals/getGlobalSchemaTool.ts

@@ -1,4 +1,5 @@
 import { getAccessResults, getGlobalInputSchema, getGlobalSchemaInputSchema } from 'payload'
+import { getLLMInstructions } from 'payload/internal'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineGlobalTool } from '../../../defineTool.js'
@@ -16,7 +17,7 @@ export const getGlobalSchemaTool = defineGlobalTool({
     readOnlyHint: true,
     title: 'Get Global Schema',
   },
-  description: 'Get the input schema for updating a global.',
+  description: 'Get the input schema and LLM instructions before updating a global.',
   input: getGlobalSchemaInputSchema,
 }).handler(async ({ slug, authorizedMCP, req }) => {
   const permissions = authorizedMCP.overrideAccess
@@ -48,16 +49,25 @@ export const getGlobalSchemaTool = defineGlobalTool({
     }
   }
 
+  const instructions = await getLLMInstructions({
+    slug,
+    type: 'global',
+    overrideAccess: authorizedMCP.overrideAccess,
+    req,
+  })
+
   return {
     content: [
       {
         type: 'text',
         text: `Schema for global "${slug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\``,
       },
+      ...(instructions ? [{ type: 'text' as const, text: instructions }] : []),
     ],
     structuredContent: {
       slug,
       schema: inputSchema,
+      ...(instructions ? { instructions } : {}),
     },
   }
 })

package/src/mcp/sanitizeMCPConfig.ts

@@ -103,6 +103,7 @@ export const sanitizeMCPConfig = ({
     hooks: pluginConfig.hooks,
     items,
     mcp: pluginConfig.mcp,
+    oauth: pluginConfig.oauth,
     overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
   }
 }

package/src/stdio.ts

@@ -3,7 +3,7 @@ import type { Config, Plugin, SanitizedConfig } from 'payload'
 /* eslint-disable no-console */
 import { serveStdio } from '@modelcontextprotocol/server/stdio'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { createLocalReq, getPayload } from 'payload'
+import { createPayloadRequest, getPayload } from 'payload'
 import { findConfig, loadEnv } from 'payload/node'
 
 import type { SanitizedMCPPluginConfig } from './types.js'
@@ -91,7 +91,7 @@ export const runMcpStdio = async (): Promise<void> => {
     headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
   }
 
-  const req = await createLocalReq({ req: { headers } }, payload)
+  const req = await createPayloadRequest({ payload, req: { headers } })
   req.payloadAPI = 'MCP' as const
   const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
 

package/src/types.ts

@@ -1,8 +1,9 @@
 import type {
   CallToolResult,
   ContentBlock,
+  Implementation,
   JsonSchemaType,
-  McpServer,
+  McpServerOptions,
   ResourceTemplate,
   ServerContext,
   StandardSchemaWithJSON,
@@ -279,9 +280,50 @@ export type MCPPluginConfig = {
     afterToolCall?: MCPAfterToolCallHook[]
   }
   mcp?: {
+    /**
+     * Largest HTTP request body, in bytes, that the MCP endpoint accepts. Larger requests
+     * are answered with `413`. Base64 file uploads count toward this limit.
+     *
+     * @default 4194304 (4 MiB, the MCP SDK default)
+     */
+    maxRequestBodySize?: number
     serverOptions?: MCPServerOptions
     verboseLogs?: boolean
   }
+  /**
+   * Lets MCP clients sign in through an OAuth authorization server. MCP requests without an
+   * authenticated user get a `401` that points to the protected resource metadata (RFC 9728),
+   * served by `oauthProtectedResourceHandler`. Payload's auth strategies must accept the
+   * issued access tokens.
+   */
+  oauth?: {
+    /**
+     * Called on MCP requests with a bearer token that Payload's auth strategies didn't accept.
+     *  Return the Payload user, including its `collection`, or `null` to answer with the OAuth challenge.
+     */
+    authenticate?: (args: {
+      req: PayloadRequest
+      token: string
+    }) => MaybePromise<PayloadRequest['user']>
+    /**
+     * The authorization servers that issue access tokens for MCP clients. Clients require each one
+     * to exactly match the `issuer` in that server's metadata, so pass a function when the exact
+     * value is only known at runtime, e.g. from the server's OpenID configuration.
+     */
+    authorizationServers: (() => MaybePromise<string[]>) | string[]
+    /**
+     * The URL clients call to reach the MCP endpoint.
+     *
+     * @default the absolute URL of `/api/mcp`, based on `serverURL` or the request URL
+     */
+    resource?: string
+    /**
+     * Scopes MCP clients should request, e.g. `['openid', 'email', 'profile']`. Without them,
+     * clients request none, which some authorization servers reject or answer with a token that
+     * doesn't identify the user.
+     */
+    scopes?: string[]
+  }
   /**
    * Replace the default MCP authorization resolver.
    *
@@ -301,11 +343,11 @@ export type MCPPluginConfig = {
 
 export type SanitizedMCPPluginConfig = {
   items: MCPItem[]
-} & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
+} & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'oauth' | 'overrideGetAuthorizedMCP'>
 
 export type MCPServerOptions = {
-  options?: ConstructorParameters<typeof McpServer>[1]
-  serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
+  options?: McpServerOptions
+  serverInfo?: Partial<Implementation>
 }
 
 /**