@payloadcms/plugin-mcp 4.0.0-internal.011fd46 → 4.0.0-internal.0731f09

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-internal.011fd46",
+  "version": "4.0.0-internal.0731f09",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
-    "plugin",
     "mcp",
-    "model context protocol"
+    "model context protocol",
+    "plugin"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/payloadcms/payload.git",
-    "directory": "packages/plugin-mcp"
-  },
   "license": "MIT",
   "author": "Payload <dev@payloadcms.com> (https://payloadcms.com)",
   "maintainers": [
@@ -21,10 +16,22 @@
       "url": "https://payloadcms.com"
     }
   ],
-  "sideEffects": [
-    "*.css"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/payloadcms/payload.git",
+    "directory": "packages/plugin-mcp"
+  },
+  "bin": {
+    "payload-mcp": "./bin.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "bin.js"
   ],
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -40,40 +47,24 @@
       "import": "./dist/stdio.js",
       "types": "./dist/stdio.d.ts",
       "default": "./dist/stdio.js"
+    },
+    "./internal": {
+      "import": "./dist/exports/internal.js",
+      "types": "./dist/exports/internal.d.ts",
+      "default": "./dist/exports/internal.js"
     }
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "payload-mcp": "./bin.js"
-  },
-  "files": [
-    "src",
-    "dist",
-    "bin.js"
-  ],
   "dependencies": {
-    "@cfworker/json-schema": "^4.1.1",
-    "@modelcontextprotocol/server": "2.0.0-alpha.2",
-    "tsx": "4.22.4",
-    "zod": "^4.0.0",
-    "@payloadcms/translations": "4.0.0-internal.011fd46"
+    "@modelcontextprotocol/server": "2.3.1",
+    "tsx": "4.23.15"
   },
   "devDependencies": {
-    "@types/react": "19.2.14",
-    "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
-    "@payloadcms/ui": "4.0.0-internal.011fd46",
-    "payload": "4.0.0-internal.011fd46",
-    "@payloadcms/eslint-config": "3.28.0"
+    "payload": "4.0.0-internal.0731f09"
   },
   "peerDependencies": {
-    "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
-    "@payloadcms/ui": "4.0.0-internal.011fd46",
-    "payload": "4.0.0-internal.011fd46"
+    "payload": "4.0.0-internal.0731f09"
   },
   "//deps_notes": {
-    "zod": "zod is a hard dependency of @modelcontextprotocol/server, thus we can safely use it without it impacting bundle size. Make extra sure the zod version here matches exactly what's defined in the dependencies of @modelcontextprotocol/server to avoid duplicate versions being installed.",
-    "@cfworker/json-schema": "Should be able to remove in next @modelcontextprotocol/server alpha release. Marked as an optional peer of @modelcontextprotocol/server, but its bundle does an eager top-level `import { Validator } from '@cfworker/json-schema'`, so it must be installed even when only zod-registered tools are used. Drop once upstream lazy-loads the validator. See: https://github.com/modelcontextprotocol/typescript-sdk",
     "tsx": "Required by the `bin.js` stdio mcp. Keep the version pinned to whatever `payload` ships to avoid duplicate installs."
   },
   "homepage:": "https://payloadcms.com",
@@ -83,9 +74,7 @@
     "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
     "clean": "rimraf {dist,*.tsbuildinfo}",
-    "copyfiles": "copyfiles -u 1 \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
+    "copyfiles": "copyfiles -u 1 -e \"**/*.spec.*\" \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
     "pack:plugin": "pnpm build && pnpm pack"
   }
 }

package/src/defaultAccess.ts

@@ -0,0 +1,3 @@
+import type { MCPAccessArgs } from './types.js'
+
+export const defaultAccess = ({ req }: MCPAccessArgs): boolean => Boolean(req.user)

package/src/endpoint/access.ts

@@ -1,144 +1,120 @@
-import type { DefaultDocumentIDType, PayloadRequest, TypedUser } from 'payload'
+import type { PayloadRequest, SanitizedPermissions } from 'payload'
 
-import crypto from 'crypto'
-import { UnauthorizedError } from 'payload'
+import { executeAuthStrategies, getAccessResults, UnauthorizedError } from 'payload'
 
-import type { AuthorizedMCP, MCPAPIKeysDoc } from '../types.js'
+import type { AuthorizedMCP, MCPItem } from '../types.js'
 
-import { getLogger } from '../utils/getLogger.js'
 import { getPluginConfig } from '../utils/getPluginConfig.js'
 
+export type GetAuthorizedMCPArgs = {
+  overrideAccess: boolean
+  req: PayloadRequest
+}
+
 /**
- * Resolves the API key (or dev-mode session) and returns the items the caller
- * may use. Denied items are dropped from the array.
+ * Authenticates an MCP request and removes items the user cannot access.
+ * `overrideAccess` skips Payload and MCP item access checks.
  */
-export const getAuthorizedMCP: (args: { req: PayloadRequest }) => Promise<AuthorizedMCP> = async ({
+export const getAuthorizedMCP: (args: GetAuthorizedMCPArgs) => Promise<AuthorizedMCP> = async ({
+  overrideAccess,
   req,
 }) => {
-  const logger = getLogger({ payload: req.payload })
   const pluginConfig = getPluginConfig({ config: req.payload.config })
 
-  const authHeader = req.headers.get('Authorization')
-  const hasBearerToken = authHeader?.startsWith('Bearer ')
-
-  const buildAuthorized = (apiKeyDoc: MCPAPIKeysDoc): AuthorizedMCP => ({
-    items: pluginConfig.items.filter((item) => {
-      switch (item.type) {
-        case 'collectionTool':
-          return apiKeyDoc.access.collections?.[item.collectionSlug]?.[item.configKey] !== false
-        case 'globalTool':
-          return apiKeyDoc.access.globals?.[item.globalSlug]?.[item.configKey] !== false
-        case 'prompt':
-          return apiKeyDoc.access.prompts?.[item.configKey] !== false
-        case 'resource':
-          return apiKeyDoc.access.resources?.[item.configKey] !== false
-        case 'tool':
-          return apiKeyDoc.access.tools?.[item.configKey] !== false
-      }
-    }),
-    overrideAccess:
-      typeof apiKeyDoc.overrideAccess === 'boolean' ? apiKeyDoc.overrideAccess : false,
-    user: apiKeyDoc.user,
-  })
-
-  if (pluginConfig.overrideAuth) {
-    return await pluginConfig.overrideAuth({
-      getAPIKeyDoc: (overrideApiKey) => getAPIKeyDoc({ logger, overrideApiKey, pluginConfig, req }),
-      getAuthorizedMCP: ({ apiKeyDoc }) => buildAuthorized(apiKeyDoc),
+  if (pluginConfig.overrideGetAuthorizedMCP) {
+    return await pluginConfig.overrideGetAuthorizedMCP({
+      overrideAccess,
       pluginConfig,
       req,
     })
   }
 
-  if (process.env.NODE_ENV === 'development' && !hasBearerToken) {
-    logger.info('Dev mode: skipping API key check, using session user')
-    return buildAuthorized({
-      id: -1,
-      access: {},
-      overrideAccess: true,
-      user: req.user ?? null,
-    })
+  if (req.headers) {
+    const headers = new Headers(req.headers)
+    const hasAuthorization = headers.has('Authorization')
+
+    headers.set('DisableAutologin', 'true')
+    // 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 })
+    }
+
+    // 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)
+    }
   }
 
-  return buildAuthorized(await getAPIKeyDoc({ logger, pluginConfig, req }))
+  return {
+    items: await filterMCPItems({
+      items: pluginConfig.items,
+      overrideAccess,
+      req,
+    }),
+    overrideAccess,
+  }
 }
 
-const getAPIKeyDoc = async ({
-  logger,
-  overrideApiKey,
-  pluginConfig,
+export const filterMCPItems = async ({
+  items,
+  overrideAccess,
   req,
 }: {
-  logger: ReturnType<typeof getLogger>
-  overrideApiKey?: string
-  pluginConfig: ReturnType<typeof getPluginConfig>
+  items: MCPItem[]
+  overrideAccess: boolean
   req: PayloadRequest
-}): Promise<MCPAPIKeysDoc> => {
-  const authHeader = req.headers.get('Authorization')
-  const hasBearerToken = authHeader?.startsWith('Bearer ')
-
-  const apiKey =
-    overrideApiKey ?? (hasBearerToken ? authHeader?.replace('Bearer ', '').trim() || null : null)
-
-  if (!apiKey) {
-    throw new UnauthorizedError()
-  }
-
-  const sha256APIKeyIndex = crypto
-    .createHmac('sha256', req.payload.secret)
-    .update(apiKey)
-    .digest('hex')
-
-  const doc = await req.payload.db.findOne<MCPAPIKeysDoc>({
-    collection: 'payload-mcp-api-keys',
-    req,
-    where: {
-      apiKeyIndex: { equals: sha256APIKeyIndex },
-    },
-  })
-
-  if (!doc || !doc.user) {
-    throw new UnauthorizedError()
+}): Promise<MCPItem[]> => {
+  // Match Payload core: overrideAccess bypasses access evaluation
+  if (overrideAccess) {
+    return items
   }
 
-  logger.info('API Key is valid')
-
-  const userRef = doc.user
-  const userID =
-    typeof userRef === 'object' && userRef !== null && 'id' in userRef
-      ? userRef.id
-      : (userRef as unknown as DefaultDocumentIDType)
+  const authorizedItems: MCPItem[] = []
 
-  const user = (await req.payload.findByID({
-    id: userID,
-    collection: pluginConfig.userCollection,
-    depth: 0,
-    disableErrors: true,
-    req,
-  })) as null | TypedUser
+  const permissions = await getAccessResults({ req })
 
-  if (!user) {
-    throw new UnauthorizedError()
+  for (const item of items) {
+    if (!(await checkItemAccess({ item, permissions, req }))) {
+      continue
+    }
+    authorizedItems.push(item)
   }
 
-  try {
-    await req.payload.db.updateOne({
-      id: doc.id,
-      collection: 'payload-mcp-api-keys',
-      data: { lastUsed: new Date().toISOString() },
-      req,
-      returning: false,
-    })
-  } catch (err) {
-    logger.warn({ err, msg: 'Failed to update MCP API key last-used timestamp' })
-  }
+  return authorizedItems
+}
 
-  return {
-    ...doc,
-    user: {
-      ...user,
-      _strategy: 'mcp-api-key' as const,
-      collection: pluginConfig.userCollection,
-    },
+/**
+ * Runs MCP item access callbacks
+ */
+const checkItemAccess = async ({
+  item,
+  permissions,
+  req,
+}: {
+  item: MCPItem
+  permissions?: SanitizedPermissions
+  req: PayloadRequest
+}): Promise<boolean> => {
+  switch (item.type) {
+    case 'collectionTool':
+      return (
+        !item.tool.access ||
+        (await item.tool.access({ slug: item.collectionSlug, permissions, req }))
+      )
+    case 'globalTool':
+      return (
+        !item.tool.access || (await item.tool.access({ slug: item.globalSlug, permissions, req }))
+      )
+    case 'prompt':
+      return !item.prompt.access || (await item.prompt.access({ permissions, req }))
+    case 'resource':
+      return !item.resource.access || (await item.resource.access({ permissions, req }))
+    case 'tool':
+      return !item.tool.access || (await item.tool.access({ permissions, req }))
   }
 }

package/src/endpoint/index.ts

@@ -1,9 +1,17 @@
-import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server'
-import { APIError, type PayloadHandler } from 'payload'
+import type { PayloadHandler, PayloadRequest } from 'payload'
+
+import {
+  createMcpHandler,
+  isLegacyRequest,
+  readRequestBody,
+  WebStandardStreamableHTTPServerTransport,
+} from '@modelcontextprotocol/server'
+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) {
@@ -11,25 +19,97 @@ 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 authorizedMCP = await getAuthorizedMCP({ req })
+  const overrideAccessParam = new URL(req.url).searchParams.get('overrideAccess')
+
+  if (overrideAccessParam !== null && process.env.NODE_ENV !== 'development') {
+    throw new APIError('MCP overrideAccess is only available in development.', 400)
+  }
+
+  let overrideAccess = false
+  if (overrideAccessParam === 'true') {
+    overrideAccess = true
+  } else if (overrideAccessParam !== null && overrideAccessParam !== 'false') {
+    throw new APIError('MCP overrideAccess must be "true" or "false".', 400)
+  }
+
+  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+
+  if (pluginConfig.oauth && !req.user) {
+    return oauthChallenge({ req })
+  }
 
-  const server = buildMcpServer({ authorizedMCP, pluginConfig, 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 })
 
-  const transport = new WebStandardStreamableHTTPServerTransport({
-    enableJsonResponse: true,
-    sessionIdGenerator: undefined, // stateless mode
+  // Keep the old JSON-only, stateless behavior because the SDK's 2025 fallback uses SSE.
+  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) => {
+      req.payload.logger.error({ err, msg: 'Error serving legacy MCP request' })
+    }
+
+    try {
+      await server.connect(transport)
+      return await transport.handleRequest(mcpRequest, { parsedBody })
+    } finally {
+      await server.close().catch((err) => {
+        req.payload.logger.error({ err, msg: 'Error closing MCP server' })
+      })
+    }
+  }
+
+  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) => {
+      req.payload.logger.error({ err, msg: 'Error serving modern MCP request' })
+    },
+    responseMode: 'json',
   })
 
-  await server.connect(transport)
+  try {
+    return await handler.fetch(mcpRequest, { parsedBody })
+  } finally {
+    await handler.close().catch((err) => {
+      req.payload.logger.error({ err, msg: 'Error closing modern MCP handler' })
+    })
+  }
+}
 
-  const mcpRequest = new Request(req.url, {
-    body: req.body,
-    duplex: 'half',
-    headers: req.headers,
-    method: req.method,
-  } as { duplex: 'half' } & RequestInit)
+/**
+ * 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
+  }
 
-  return await transport.handleRequest(mcpRequest)
+  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,91 @@
+import type { OAuthProtectedResourceMetadata } from '@modelcontextprotocol/server'
+import type { PayloadHandler, PayloadRequest, SanitizedConfig } from 'payload'
+
+import {
+  bearerAuthChallengeResponse,
+  OAuthError,
+  OAuthErrorCode,
+} from '@modelcontextprotocol/server'
+import { createPayloadRequest, getPayload } from 'payload'
+
+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({ req })
+
+/**
+ * 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({
+      req: await createPayloadRequest({ payload: await getPayload({ config }), req: request }),
+    })
+
+/**
+ * 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 => {
+  const { oauth } = getPluginConfig({ config: req.payload.config })
+  const response = bearerAuthChallengeResponse(
+    new OAuthError(OAuthErrorCode.InvalidToken, req.t('error:unauthorized')),
+    {
+      requiredScopes: oauth?.type === 'external' ? oauth.scopes : undefined,
+      resourceMetadataUrl: `${getMCPURL({ config: req.payload.config, url: req.url! })}/oauth-protected-resource`,
+    },
+  )
+
+  // Lets browser-based MCP clients read the challenge, when Payload's `cors` setting allows them
+  response.headers.set('Access-Control-Expose-Headers', 'WWW-Authenticate')
+
+  return response
+}
+
+/**
+ * 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 })
+
+export const getMCPURL = ({ config, url }: { config: SanitizedConfig; url: string }): string =>
+  new URL(`${config.routes.api}/mcp`, config.serverURL || url).href
+
+const getMetadataResponse = async ({ req }: { req: PayloadRequest }): Promise<Response> => {
+  const { config } = req.payload
+  const { oauth } = getPluginConfig({ config })
+
+  if (!oauth) {
+    return new Response(null, { status: 404 })
+  }
+
+  return Response.json(
+    {
+      authorization_servers:
+        oauth.type === 'builtin'
+          ? [`${getMCPURL({ config, url: req.url! })}/oauth`]
+          : typeof oauth.authorizationServers === 'function'
+            ? await oauth.authorizationServers({ req })
+            : oauth.authorizationServers,
+      bearer_methods_supported: ['header'],
+      resource: getMCPResource({ config, url: req.url! }),
+      scopes_supported: oauth.type === 'external' ? oauth.scopes : undefined,
+    } satisfies OAuthProtectedResourceMetadata,
+    // Public document, readable by browser-based MCP clients on any origin
+    { headers: { 'Access-Control-Allow-Origin': '*' } },
+  )
+}