@payloadcms/plugin-mcp 4.0.0-internal.21664f3 → 4.0.0-internal.22d1431

package/src/endpoint/access.ts

@@ -1,10 +1,11 @@
 import type { PayloadRequest, SanitizedPermissions } from 'payload'
 
-import { getAccessResults, UnauthorizedError } from 'payload'
+import { executeAuthStrategies, getAccessResults, UnauthorizedError } from 'payload'
 
 import type { AuthorizedMCP, MCPItem } from '../types.js'
 
 import { getPluginConfig } from '../utils/getPluginConfig.js'
+import { authenticateLoginToken } from './oauthLoginToken.js'
 
 export type GetAuthorizedMCPArgs = {
   overrideAccess: boolean
@@ -34,9 +35,27 @@ 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 get here, 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]
+    // Sealed Payload login tokens from the built-in OAuth server
+    if (
+      !req.user &&
+      bearerToken &&
+      pluginConfig.oauth?.type === 'builtin' &&
+      !pluginConfig.oauth.issueToken
+    ) {
+      req.user = await authenticateLoginToken({ req, token: bearerToken })
+    }
+    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)
     }
   }
@@ -95,12 +114,11 @@ const checkItemAccess = async ({
     case 'collectionTool':
       return (
         !item.tool.access ||
-        (await item.tool.access({ collectionSlug: item.collectionSlug, permissions, req }))
+        (await item.tool.access({ slug: item.collectionSlug, permissions, req }))
       )
     case 'globalTool':
       return (
-        !item.tool.access ||
-        (await item.tool.access({ globalSlug: item.globalSlug, permissions, req }))
+        !item.tool.access || (await item.tool.access({ slug: item.globalSlug, permissions, req }))
       )
     case 'prompt':
       return !item.prompt.access || (await item.prompt.access({ permissions, req }))

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,92 @@
+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. Not cached, since
+    // without `serverURL` its URLs come from the request.
+    { headers: { 'Access-Control-Allow-Origin': '*', 'Cache-Control': 'no-store' } },
+  )
+}

package/src/endpoint/oauthLoginToken.ts

@@ -0,0 +1,91 @@
+import type { PayloadRequest } from 'payload'
+
+import { APIError, createAuthToken, executeAuthStrategies, refreshAuthToken } from 'payload'
+
+import type { MCPOAuthTokens } from '../types.js'
+
+import { seal, unseal } from '../utils/seal.js'
+
+/**
+ * The default `issueToken`: a Payload login token, sealed so it only works for MCP, where
+ * `authenticateLoginToken` unseals it. Otherwise an MCP client could use it as the user's admin
+ * panel login. When the collection uses sessions, the client also gets a refresh token.
+ */
+export const issueLoginToken = async ({
+  req,
+}: {
+  req: PayloadRequest
+}): Promise<MCPOAuthTokens> => {
+  const collectionConfig = req.payload.collections[req.user!.collection]!.config
+
+  if (collectionConfig.auth.disableLocalStrategy) {
+    throw new APIError(
+      `MCP clients can't get Payload login tokens for the "${collectionConfig.slug}" collection because its local strategy is disabled. Pass oauth.issueToken to the MCP plugin.`,
+    )
+  }
+
+  // The full document, like the one a password login starts its session on
+  const user = (await req.payload.db.findOne<NonNullable<PayloadRequest['user']>>({
+    collection: collectionConfig.slug,
+    req,
+    where: { id: { equals: req.user!.id } },
+  }))!
+
+  const { refreshToken, token } = await createAuthToken({
+    collectionConfig,
+    email: user.email!,
+    req,
+    shouldCreateRefreshToken: true,
+    user,
+  })
+
+  return {
+    accessToken: sealLoginToken({ req, token }),
+    expiresIn: collectionConfig.auth.tokenExpiration,
+    refreshToken,
+  }
+}
+
+/** The default `refreshToken`. Payload logs out the session when a refresh token is reused. */
+export const refreshLoginToken = async ({
+  refreshToken,
+  req,
+}: {
+  refreshToken: string
+  req: PayloadRequest
+}): Promise<MCPOAuthTokens | null> => {
+  const refreshed = await refreshAuthToken({ refreshToken, req })
+
+  return (
+    refreshed && {
+      accessToken: sealLoginToken({ req, token: refreshed.token }),
+      expiresIn: refreshed.collectionConfig.auth.tokenExpiration,
+      refreshToken: refreshed.refreshToken,
+    }
+  )
+}
+
+/** Finds the user of an MCP request's access token from `issueLoginToken`. */
+export const authenticateLoginToken = async ({
+  req,
+  token,
+}: {
+  req: PayloadRequest
+  token: string
+}): Promise<PayloadRequest['user']> => {
+  const loginToken = unseal<{ token: string }>({ type: 'access', req, value: token })
+
+  if (!loginToken) {
+    return null
+  }
+
+  const headers = new Headers({
+    Authorization: `JWT ${loginToken.token}`,
+    DisableAutologin: 'true',
+  })
+
+  return (await executeAuthStrategies({ headers, payload: req.payload, req })).user
+}
+
+const sealLoginToken = ({ req, token }: { req: PayloadRequest; token: string }): string =>
+  seal({ type: 'access', data: { token }, req })