@payloadcms/plugin-mcp 4.0.0-internal.d28e9fb → 4.0.0-internal.d7d662c

package/src/endpoint/index.ts

@@ -0,0 +1,115 @@
+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) {
+    throw new APIError('Missing request URL', 400)
+  }
+
+  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')
+
+  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 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, 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',
+  })
+
+  try {
+    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,90 @@
+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 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`,
+    },
+  )
+
+  // 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 })
+
+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 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({ req })
+          : authorizationServers,
+      bearer_methods_supported: ['header'],
+      resource: getMCPResource({ config, url: req.url! }),
+      scopes_supported: scopes,
+    } satisfies OAuthProtectedResourceMetadata,
+    // Public document, readable by browser-based MCP clients on any origin
+    { headers: { 'Access-Control-Allow-Origin': '*' } },
+  )
+}

package/src/exports/client.ts

@@ -0,0 +1,3 @@
+'use client'
+
+export {}

package/src/exports/internal.ts

@@ -0,0 +1 @@
+export { filterMCPItems, getAuthorizedMCP } from '../endpoint/access.js'

package/src/index.ts

@@ -1,113 +1,72 @@
 import { definePlugin } from 'payload'
 
-import type { MCPAccessSettings, MCPPluginConfig } from './types.js'
+import type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig } from './types.js'
 
-import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
-import { initializeMCPHandler } from './endpoints/mcp.js'
+import { mcpEndpoint } from './endpoint/index.js'
+import { oauthProtectedResourceEndpoint } from './endpoint/oauth.js'
+import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
 
 declare module 'payload' {
-  export interface PayloadRequest {
-    payloadAPI: 'GraphQL' | 'local' | 'MCP' | 'REST'
+  export interface PayloadRequestAPI {
+    MCP: true
   }
   interface RegisteredPlugins {
+    /** 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
+    }
+  }
 }
 
-import { defaults } from './defaults.js'
+export type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig }
 
-export type { MCPAccessSettings, MCPPluginConfig }
+export { defineCollectionTool, defineGlobalTool, definePrompt, defineTool } from './defineTool.js'
+export { oauthProtectedResourceHandler } from './endpoint/oauth.js'
 
-/**
- * The MCP Plugin for Payload. This plugin allows you to add MCP capabilities to your Payload project.
- *
- * @param pluginOptions - The options for the MCP plugin.
- */
 export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
   order: 10,
-  plugin: ({ config, plugins: _plugins, ...pluginOptions }) => {
-    if (!config.collections) {
-      config.collections = []
-    }
-
-    // Collections
-    const collections = pluginOptions.collections || {}
-    // Globals
-    const globals = pluginOptions.globals || {}
-    // Extract custom tools for the global config
-    const customTools =
-      pluginOptions.mcp?.tools?.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-      })) || []
-
-    // User Collection
-    pluginOptions.userCollection =
-      pluginOptions.userCollection ?? config?.admin?.user ?? defaults.userCollection
+  plugin: ({ config, options, plugins }) => {
+    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: options })
 
-    const experimentalTools = pluginOptions?.experimental?.tools || {}
-
-    /**
-     * API Keys
-     * --------
-     * High resolution control over MCP capabilities is crucial when using Payload with LLMs.
-     *
-     * This API Keys collection has ways for admins to create API keys and allow or disallow the MCP capabilities.
-     * This is useful when Admins want to allow or disallow the use of the MCP capabilities in real time.
-     * For example:
-     *  - If a collection has all of its capabilities enabled, admins can allow or disallow the create, update, delete, and find capabilities on that collection.
-     *  - If a collection only has the find capability enabled, admins can only allow or disallow the find capability on that collection.
-     *  - If a global has all of its capabilities enabled, admins can allow or disallow the find and update capabilities on that global.
-     *  - If a custom tool has gone haywire, admins can disallow that tool.
-     *
-     */
-    const apiKeyCollection = createAPIKeysCollection(
-      collections,
-      globals,
-      customTools,
-      experimentalTools,
-      pluginOptions,
-    )
-    if (pluginOptions.overrideApiKeyCollection) {
-      config.collections.push(pluginOptions.overrideApiKeyCollection(apiKeyCollection))
-    } else {
-      config.collections.push(apiKeyCollection)
+    // Stash the sanitized config on plugin options so `getPluginConfig()` reads it.
+    const registered = plugins['@payloadcms/plugin-mcp']
+    if (registered) {
+      // @ts-expect-error
+      registered.sanitizedOptions = pluginConfig
     }
 
-    /**
-     * If the plugin is disabled, we still want to keep added collections/fields so the database schema is consistent which is important for migrations.
-     * If your plugin heavily modifies the database schema, you may want to remove this property.
-     */
-    if (pluginOptions.disabled) {
+    if (pluginConfig.disabled) {
       return config
     }
 
-    if (!config.endpoints) {
-      config.endpoints = []
+    return {
+      ...config,
+      endpoints: [
+        ...(config.endpoints ?? []),
+        // 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',
+        },
+      ],
     }
-
-    /**
-     * This is the primary MCP Server Endpoint.
-     * Payload will automatically add the /api prefix to the path, so the full path is `/api/mcp`
-     * NOTE: This is only transport method until we add full support for SSE which will be another endpoint at `/api/sse`
-     */
-    config.endpoints.push({
-      handler: initializeMCPHandler(pluginOptions),
-      method: 'post',
-      path: '/mcp',
-    })
-
-    /**
-     * The GET response is always: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."},"id":null} -- even with an API key
-     * This is expected behavior and MCP clients should always use the POST endpoint.
-     */
-    config.endpoints.push({
-      handler: initializeMCPHandler(pluginOptions),
-      method: 'get',
-      path: '/mcp',
-    })
-
-    return config
   },
 })

package/src/mcp/buildMcpServer.ts

@@ -0,0 +1,294 @@
+import type { PayloadRequest } from 'payload'
+
+import { McpServer, type ServerContext } from '@modelcontextprotocol/server'
+import { APIError, strictObject, z } from 'payload'
+
+import type {
+  AuthorizedMCP,
+  CollectionMCPItem,
+  GlobalMCPItem,
+  JsonSchemaType,
+  MCPResponseOverride,
+  MCPToolResponse,
+  SanitizedMCPPluginConfig,
+  ToolInputSchema,
+} from '../types.js'
+
+import { getLogger } from '../utils/getLogger.js'
+import { toStandardSchema } from '../utils/toStandardSchema.js'
+
+/**
+ * Serving-entry-agnostic core: registers every authorized MCP item onto a fresh
+ * `McpServer` and returns it. The HTTP and stdio entry point callers provide fresh
+ * instances from this builder while they own the transport and protocol-era
+ * decision.
+ *
+ * `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 `createPayloadRequest`.
+ */
+export const buildMcpServer = ({
+  authorizedMCP,
+  pluginConfig,
+  req,
+}: {
+  authorizedMCP: AuthorizedMCP
+  pluginConfig: SanitizedMCPPluginConfig
+  req: PayloadRequest
+}): McpServer => {
+  z.config(z.locales.en())
+
+  const serverOptions = pluginConfig.mcp?.serverOptions || {}
+  const server = new McpServer(
+    { name: 'Payload MCP Server', version: '1.0.0', ...serverOptions.serverInfo },
+    serverOptions.options,
+  )
+
+  const logger = getLogger({ payload: req.payload })
+
+  /**
+   * Wrap a tool handler's response with the tool's `overrideResponse`, then
+   * strip the internal `doc` field so it doesn't leak onto the wire.
+   */
+  const finalizeToolResponse = async ({
+    input,
+    overrideResponse,
+    response,
+    toolName,
+  }: {
+    input: unknown
+    overrideResponse?: MCPResponseOverride
+    response: MCPToolResponse
+    toolName: string
+  }): Promise<MCPToolResponse> => {
+    let overridden = overrideResponse?.(response, response.doc ?? {}, req) ?? response
+    for (const hook of pluginConfig.hooks?.afterToolCall ?? []) {
+      overridden = await hook({ input, req, response: overridden, toolName })
+    }
+    const { doc: _doc, ...rest } = overridden
+    return rest
+  }
+
+  /**
+   * Runs a collection/global tool call:
+   * - reads `slug` from the input
+   * - runs access control: errors if `authorizedMCP.items` has no entry for this tool + slug
+   * - runs the tool handler and finalizes its response
+   */
+  const callEntityTool = async ({
+    input,
+    item,
+    serverContext,
+  }: {
+    input: unknown
+    item: CollectionMCPItem | GlobalMCPItem
+    serverContext: ServerContext
+  }): Promise<MCPToolResponse> => {
+    const entity = item.type === 'collectionTool' ? 'collection' : 'global'
+    const toolInput = (input ?? {}) as Record<string, unknown>
+    const slug = toolInput.slug as string | undefined
+
+    if (!slug) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: "${item.mcpName}" requires slug. Use getConfigInfo to inspect ${entity} slugs.`,
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    const match = authorizedMCP.items.find(
+      (candidate): candidate is CollectionMCPItem | GlobalMCPItem =>
+        candidate.type === item.type &&
+        candidate.mcpName === item.mcpName &&
+        (candidate.type === 'collectionTool'
+          ? candidate.collectionSlug === slug
+          : candidate.type === 'globalTool' && candidate.globalSlug === slug),
+    )
+
+    if (!match) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: MCP access to "${item.mcpName}" is not enabled for ${entity} "${slug}"`,
+          },
+        ],
+        isError: true,
+      }
+    }
+
+    const handlerArgs = {
+      authorizedMCP,
+      input: toolInput,
+      req,
+      serverContext,
+    }
+    const response = await (match.type === 'collectionTool'
+      ? match.tool.handler({ ...handlerArgs, slug })
+      : match.tool.handler({ ...handlerArgs, slug }))
+
+    return finalizeToolResponse({
+      input: toolInput,
+      overrideResponse: match.tool.overrideResponse,
+      response,
+      toolName: match.mcpName,
+    })
+  }
+
+  try {
+    const registeredEntityTools = new Set<string>()
+
+    for (const item of authorizedMCP.items) {
+      switch (item.type) {
+        case 'collectionTool':
+        case 'globalTool': {
+          if (registeredEntityTools.has(item.mcpName)) {
+            break
+          }
+          registeredEntityTools.add(item.mcpName)
+
+          const inputSchema = withSlugInput({ input: item.tool.input })
+
+          server.registerTool(
+            item.mcpName,
+            {
+              annotations: item.tool.annotations,
+              description: item.tool.description,
+              inputSchema: toStandardSchema(inputSchema),
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              callEntityTool({ input, item, serverContext: ctx }),
+          )
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
+          break
+        }
+        case 'prompt': {
+          const prompt = item.prompt
+          server.registerPrompt(
+            item.mcpName,
+            {
+              argsSchema: prompt.argsSchema ? toStandardSchema(prompt.argsSchema) : undefined,
+              description: prompt.description,
+              title: prompt.title,
+            },
+            async (input: unknown, ctx: ServerContext) =>
+              prompt.handler({
+                input: (input ?? {}) as Record<string, unknown>,
+                req,
+                serverContext: ctx,
+              }),
+          )
+          logger.info(`✅ Prompt: ${prompt.title} Registered.`)
+          break
+        }
+        case 'resource': {
+          const resource = item.resource
+          server.registerResource(
+            item.mcpName,
+            // @ts-expect-error - Overload type ambiguity (string OR ResourceTemplate is valid)
+            resource.uri,
+            {
+              description: resource.description,
+              mimeType: resource.mimeType,
+              title: resource.title,
+            },
+            // Static URIs call (uri, ctx); ResourceTemplates call (uri, params, ctx).
+            // The rest-params shape lets us collect either signature uniformly.
+            async (...sdkArgs: unknown[]) => {
+              const ctx = sdkArgs[sdkArgs.length - 1] as ServerContext
+              const uri = sdkArgs[0] as URL
+              const params = (sdkArgs.length > 2 ? sdkArgs[1] : {}) as Record<string, string>
+              return resource.handler({ params, req, serverContext: ctx, uri })
+            },
+          )
+          logger.info(`✅ Resource: ${resource.title} Registered.`)
+          break
+        }
+        case 'tool': {
+          const tool = item.tool
+          server.registerTool(
+            item.mcpName,
+            {
+              annotations: tool.annotations,
+              description: tool.description,
+              inputSchema: tool.input ? toStandardSchema(tool.input) : undefined,
+            },
+            async (input: unknown, ctx: ServerContext) => {
+              const toolInput = (input ?? {}) as Record<string, unknown>
+              const response = await tool.handler({
+                authorizedMCP,
+                input: toolInput,
+                req,
+                serverContext: ctx,
+              })
+              return finalizeToolResponse({
+                input: toolInput,
+                overrideResponse: tool.overrideResponse,
+                response,
+                toolName: item.mcpName,
+              })
+            },
+          )
+          logger.info(`✅ Tool: ${item.mcpName} Registered.`)
+          break
+        }
+      }
+    }
+  } catch (error) {
+    throw new APIError(`Error initializing MCP handler: ${String(error)}`, 500)
+  }
+
+  return server
+}
+
+const withSlugInput = ({ input }: { input?: ToolInputSchema }): ToolInputSchema => {
+  const description = 'The target slug.'
+  const slugSchema = z.string().check(z.describe(description))
+
+  if (!input) {
+    return strictObject({ slug: slugSchema })
+  }
+
+  if (typeof input === 'object' && input !== null && '~standard' in input) {
+    const schema = input['~standard'].jsonSchema.input({ target: 'draft-2020-12' })
+    const properties = schema.properties as Record<string, unknown> | undefined
+
+    if (properties?.slug) {
+      return input
+    }
+
+    return addSlugToJSONSchema({ description, schema })
+  }
+
+  return addSlugToJSONSchema({ description, schema: input })
+}
+
+const addSlugToJSONSchema = ({
+  description,
+  schema,
+}: {
+  description: string
+  schema: JsonSchemaType
+}): JsonSchemaType => {
+  const objectSchema = schema as {
+    properties?: Record<string, JsonSchemaType>
+    required?: string[]
+  } & JsonSchemaType
+
+  return {
+    ...objectSchema,
+    type: 'object',
+    properties: {
+      ...objectSchema.properties,
+      slug: {
+        type: 'string',
+        description,
+      },
+    },
+    required: Array.from(new Set(['slug', ...(objectSchema.required ?? [])])),
+  }
+}