@payloadcms/plugin-mcp 4.0.0-internal.b8e7c89 → 4.0.0-internal.bf4bcce

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 { oauthChallenge } from './oauth.js'
 
 export const mcpEndpoint: PayloadHandler = async (req) => {
   if (!req.url) {
@@ -33,14 +35,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 +59,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 +69,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 +79,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,72 @@
+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')),
+    {
+      resourceMetadataUrl: `${getMCPURL({ config: req.payload.config, url: req.url! })}/oauth-protected-resource`,
+    },
+  )
+
+const getMCPURL = ({ config, url }: { config: SanitizedConfig; url: string }): string =>
+  new URL(`${config.routes.api}/mcp`, config.serverURL || url).href
+
+const getMetadataResponse = ({
+  config,
+  url,
+}: {
+  config: SanitizedConfig
+  url: string
+}): Response => {
+  const pluginConfig = getPluginConfig({ config })
+
+  if (!pluginConfig.oauth) {
+    return new Response(null, { status: 404 })
+  }
+
+  return Response.json(
+    {
+      authorization_servers: pluginConfig.oauth.authorizationServers,
+      bearer_methods_supported: ['header'],
+      resource: pluginConfig.oauth.resource ?? getMCPURL({ config, url }),
+    },
+    // 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' {
@@ -18,6 +19,7 @@ declare module 'payload' {
 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',
@@ -49,6 +51,11 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
           method: 'get',
           path: '/mcp',
         },
+        {
+          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,39 @@ 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']>
+    authorizationServers: 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
+  }
   /**
    * Replace the default MCP authorization resolver.
    *
@@ -301,11 +332,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>
 }
 
 /**

package/dist/mcp/builtin/collections/fileInput.spec.js

@@ -1,86 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { fileInputSchema, resolveFile } from './fileInput.js';
-describe('MCP file input', ()=>{
-    it('should reject malformed MIME types', ()=>{
-        const result = fileInputSchema.safeParse({
-            data: 'aGVsbG8=',
-            mimeType: 'text/plain\r\nx-test: value',
-            name: 'hello.txt',
-            source: 'base64'
-        });
-        expect(result.success).toBe(false);
-    });
-    it('should accept a prepared upload', ()=>{
-        const result = fileInputSchema.safeParse({
-            file: {
-                filename: 'image.png',
-                mimeType: 'image/png',
-                size: 123,
-                uploadReference: {
-                    uploadId: 'upload-id'
-                }
-            },
-            source: 'uploadReference'
-        });
-        expect(result.success).toBe(true);
-    });
-    it('should reject oversized base64 files', async ()=>{
-        const req = createRequest({
-            maxFileSize: 4
-        });
-        await expect(resolveFile({
-            slug: 'media',
-            input: {
-                data: Buffer.from('hello').toString('base64'),
-                mimeType: 'text/plain',
-                name: 'hello.txt',
-                source: 'base64'
-            },
-            req
-        })).rejects.toThrow('File exceeds the 4 byte upload limit.');
-    });
-    it('should reject URLs outside the collection allowlist', async ()=>{
-        const req = createRequest({
-            allowList: [
-                {
-                    hostname: 'assets.example.com',
-                    protocol: 'https'
-                }
-            ]
-        });
-        await expect(resolveFile({
-            slug: 'media',
-            input: {
-                source: 'externalURL',
-                url: 'https://example.com/image.png'
-            },
-            req
-        })).rejects.toThrow('The provided file URL is not allowed.');
-    });
-});
-function createRequest({ allowList, maxFileSize }) {
-    return {
-        payload: {
-            collections: {
-                media: {
-                    config: {
-                        upload: allowList ? {
-                            pasteURL: {
-                                allowList
-                            }
-                        } : {}
-                    }
-                }
-            },
-            config: {
-                upload: {
-                    limits: {
-                        fileSize: maxFileSize
-                    }
-                }
-            }
-        }
-    };
-}
-
-//# sourceMappingURL=fileInput.spec.js.map

package/dist/mcp/builtin/collections/fileInput.spec.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../src/mcp/builtin/collections/fileInput.spec.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\n\nimport { describe, expect, it } from 'vitest'\n\nimport { fileInputSchema, resolveFile } from './fileInput.js'\n\ndescribe('MCP file input', () => {\n  it('should reject malformed MIME types', () => {\n    const result = fileInputSchema.safeParse({\n      data: 'aGVsbG8=',\n      mimeType: 'text/plain\\r\\nx-test: value',\n      name: 'hello.txt',\n      source: 'base64',\n    })\n\n    expect(result.success).toBe(false)\n  })\n\n  it('should accept a prepared upload', () => {\n    const result = fileInputSchema.safeParse({\n      file: {\n        filename: 'image.png',\n        mimeType: 'image/png',\n        size: 123,\n        uploadReference: { uploadId: 'upload-id' },\n      },\n      source: 'uploadReference',\n    })\n\n    expect(result.success).toBe(true)\n  })\n\n  it('should reject oversized base64 files', async () => {\n    const req = createRequest({ maxFileSize: 4 })\n\n    await expect(\n      resolveFile({\n        slug: 'media',\n        input: {\n          data: Buffer.from('hello').toString('base64'),\n          mimeType: 'text/plain',\n          name: 'hello.txt',\n          source: 'base64',\n        },\n        req,\n      }),\n    ).rejects.toThrow('File exceeds the 4 byte upload limit.')\n  })\n\n  it('should reject URLs outside the collection allowlist', async () => {\n    const req = createRequest({\n      allowList: [{ hostname: 'assets.example.com', protocol: 'https' }],\n    })\n\n    await expect(\n      resolveFile({\n        slug: 'media',\n        input: {\n          source: 'externalURL',\n          url: 'https://example.com/image.png',\n        },\n        req,\n      }),\n    ).rejects.toThrow('The provided file URL is not allowed.')\n  })\n})\n\nfunction createRequest({\n  allowList,\n  maxFileSize,\n}: {\n  allowList?: Array<{ hostname: string; protocol: 'http' | 'https' }>\n  maxFileSize?: number\n}): PayloadRequest {\n  return {\n    payload: {\n      collections: {\n        media: {\n          config: {\n            upload: allowList ? { pasteURL: { allowList } } : {},\n          },\n        },\n      },\n      config: {\n        upload: {\n          limits: {\n            fileSize: maxFileSize,\n          },\n        },\n      },\n    },\n  } as unknown as PayloadRequest\n}\n"],"names":["describe","expect","it","fileInputSchema","resolveFile","result","safeParse","data","mimeType","name","source","success","toBe","file","filename","size","uploadReference","uploadId","req","createRequest","maxFileSize","slug","input","Buffer","from","toString","rejects","toThrow","allowList","hostname","protocol","url","payload","collections","media","config","upload","pasteURL","limits","fileSize"],"mappings":"AAEA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAE7C,SAASC,eAAe,EAAEC,WAAW,QAAQ,iBAAgB;AAE7DJ,SAAS,kBAAkB;IACzBE,GAAG,sCAAsC;QACvC,MAAMG,SAASF,gBAAgBG,SAAS,CAAC;YACvCC,MAAM;YACNC,UAAU;YACVC,MAAM;YACNC,QAAQ;QACV;QAEAT,OAAOI,OAAOM,OAAO,EAAEC,IAAI,CAAC;IAC9B;IAEAV,GAAG,mCAAmC;QACpC,MAAMG,SAASF,gBAAgBG,SAAS,CAAC;YACvCO,MAAM;gBACJC,UAAU;gBACVN,UAAU;gBACVO,MAAM;gBACNC,iBAAiB;oBAAEC,UAAU;gBAAY;YAC3C;YACAP,QAAQ;QACV;QAEAT,OAAOI,OAAOM,OAAO,EAAEC,IAAI,CAAC;IAC9B;IAEAV,GAAG,wCAAwC;QACzC,MAAMgB,MAAMC,cAAc;YAAEC,aAAa;QAAE;QAE3C,MAAMnB,OACJG,YAAY;YACViB,MAAM;YACNC,OAAO;gBACLf,MAAMgB,OAAOC,IAAI,CAAC,SAASC,QAAQ,CAAC;gBACpCjB,UAAU;gBACVC,MAAM;gBACNC,QAAQ;YACV;YACAQ;QACF,IACAQ,OAAO,CAACC,OAAO,CAAC;IACpB;IAEAzB,GAAG,uDAAuD;QACxD,MAAMgB,MAAMC,cAAc;YACxBS,WAAW;gBAAC;oBAAEC,UAAU;oBAAsBC,UAAU;gBAAQ;aAAE;QACpE;QAEA,MAAM7B,OACJG,YAAY;YACViB,MAAM;YACNC,OAAO;gBACLZ,QAAQ;gBACRqB,KAAK;YACP;YACAb;QACF,IACAQ,OAAO,CAACC,OAAO,CAAC;IACpB;AACF;AAEA,SAASR,cAAc,EACrBS,SAAS,EACTR,WAAW,EAIZ;IACC,OAAO;QACLY,SAAS;YACPC,aAAa;gBACXC,OAAO;oBACLC,QAAQ;wBACNC,QAAQR,YAAY;4BAAES,UAAU;gCAAET;4BAAU;wBAAE,IAAI,CAAC;oBACrD;gBACF;YACF;YACAO,QAAQ;gBACNC,QAAQ;oBACNE,QAAQ;wBACNC,UAAUnB;oBACZ;gBACF;YACF;QACF;IACF;AACF"}