@payloadcms/plugin-mcp 4.0.0-canary.3 → 4.0.0-canary.31

package/src/endpoint/access.ts

@@ -1,144 +1,111 @@
-import type { DefaultDocumentIDType, PayloadRequest, TypedUser } from 'payload'
+import type { PayloadRequest, SanitizedPermissions } from 'payload'
 
-import crypto from 'crypto'
-import { UnauthorizedError } from 'payload'
+import { 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')
+    req.user = (await req.payload.auth({ headers, req })).user
+
+    if (hasAuthorization && !req.user) {
+      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()
+}): Promise<MCPItem[]> => {
+  // Match Payload core: overrideAccess bypasses access evaluation
+  if (overrideAccess) {
+    return items
   }
 
-  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()
-  }
-
-  logger.info('API Key is valid')
+  const authorizedItems: MCPItem[] = []
 
-  const userRef = doc.user
-  const userID =
-    typeof userRef === 'object' && userRef !== null && 'id' in userRef
-      ? userRef.id
-      : (userRef as unknown as DefaultDocumentIDType)
+  const permissions = await getAccessResults({ req })
 
-  const user = (await req.payload.findByID({
-    id: userID,
-    collection: pluginConfig.userCollection,
-    depth: 0,
-    disableErrors: true,
-    req,
-  })) as null | TypedUser
-
-  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,5 +1,11 @@
-import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server'
-import { APIError, type PayloadHandler } from 'payload'
+import type { PayloadHandler, PayloadRequest } from 'payload'
+
+import {
+  createMcpHandler,
+  isLegacyRequest,
+  WebStandardStreamableHTTPServerTransport,
+} from '@modelcontextprotocol/server'
+import { APIError } from 'payload'
 
 import { buildMcpServer } from '../mcp/buildMcpServer.js'
 import { getPluginConfig } from '../utils/getPluginConfig.js'
@@ -13,23 +19,59 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   req.payloadAPI = 'MCP' as const
 
   const pluginConfig = getPluginConfig({ config: req.payload.config })
-  const authorizedMCP = await getAuthorizedMCP({ req })
+  const overrideAccessParam = new URL(req.url).searchParams.get('overrideAccess')
 
-  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+  if (overrideAccessParam !== null && process.env.NODE_ENV !== 'development') {
+    throw new APIError('MCP overrideAccess is only available in development.', 400)
+  }
 
-  const transport = new WebStandardStreamableHTTPServerTransport({
-    enableJsonResponse: true,
-    sessionIdGenerator: undefined, // stateless mode
-  })
+  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)
+  }
 
-  await server.connect(transport)
+  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+  // Payload augments the original web-standard Request in place.
+  const mcpRequest = req as PayloadRequest & Request
 
-  const mcpRequest = new Request(req.url, {
-    body: req.body,
-    duplex: 'half',
-    headers: req.headers,
-    method: req.method,
-  } as { duplex: 'half' } & RequestInit)
+  // Keep the old JSON-only, stateless behavior because the SDK's 2025 fallback uses SSE.
+  if (await isLegacyRequest(mcpRequest)) {
+    const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      enableJsonResponse: true,
+      sessionIdGenerator: undefined, // stateless mode
+    })
+    transport.onerror = (err) => {
+      req.payload.logger.error({ err, msg: 'Error serving legacy MCP request' })
+    }
 
-  return await transport.handleRequest(mcpRequest)
+    try {
+      await server.connect(transport)
+      return await transport.handleRequest(mcpRequest)
+    } 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',
+    // 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)
+  } finally {
+    await handler.close().catch((err) => {
+      req.payload.logger.error({ err, msg: 'Error closing modern MCP handler' })
+    })
+  }
 }

package/src/exports/client.ts

@@ -1,5 +1,3 @@
 'use client'
-export { AccessField } from '../components/AccessField/index.client.js'
-export { APIKeyField } from '../components/APIKeyField/index.client.js'
-export { APIKeysEmptyState } from '../components/APIKeysEmptyState/index.client.js'
-export { MCPSettingsMenu } from '../components/SettingsMenu/index.client.js'
+
+export {}

package/src/exports/internal.ts

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

package/src/index.ts

@@ -1,18 +1,13 @@
-import type { AcceptedLanguages } from '@payloadcms/translations'
+import { definePlugin } from 'payload'
 
-import { defaultUserCollection, definePlugin } from 'payload'
-
-import type { PluginDefaultTranslationsObject } from './translations/types.js'
 import type { AuthorizedMCP, MCPPluginConfig, SanitizedMCPPluginConfig } from './types.js'
 
-import { getAPIKeysCollection } from './collection/index.js'
 import { mcpEndpoint } from './endpoint/index.js'
 import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
-import { translations } from './translations/index.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. */
@@ -27,17 +22,8 @@ export { defineCollectionTool, defineGlobalTool, definePrompt, defineTool } from
 export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
   order: 10,
-  plugin: ({ config, plugins, ...rawConfig }) => {
-    // If a project has no auth collection yet, add the default users collection
-    // so the relationship target and default `userCollection` exist.
-    if (!config.admin?.user) {
-      const firstCollectionWithAuth = (config.collections ?? []).find(({ auth }) => Boolean(auth))
-      if (!firstCollectionWithAuth) {
-        ;(config.collections ??= []).push(defaultUserCollection)
-      }
-    }
-
-    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: rawConfig })
+  plugin: ({ config, options, plugins }) => {
+    const pluginConfig = sanitizeMCPConfig({ config, pluginConfig: options })
 
     // Stash the sanitized config on plugin options so `getPluginConfig()` reads it.
     const registered = plugins['@payloadcms/plugin-mcp']
@@ -46,55 +32,12 @@ export const mcpPlugin = definePlugin<MCPPluginConfig>({
       registered.sanitizedOptions = pluginConfig as unknown as typeof registered.options
     }
 
-    ;(config.collections ??= []).push(getAPIKeysCollection({ pluginConfig }))
-
-    if (!config.i18n) {
-      config.i18n = {}
-    }
-
-    if (!config.i18n.translations) {
-      config.i18n.translations = {}
-    }
-
-    const supportedLanguageKeys = config.i18n.supportedLanguages
-      ? Object.keys(config.i18n.supportedLanguages)
-      : ['en']
-
-    for (const lang of supportedLanguageKeys) {
-      const pluginEntry = translations[lang as keyof typeof translations]
-      if (!pluginEntry) {
-        continue
-      }
-
-      const typedLocale = lang as AcceptedLanguages
-      const existing = (config.i18n.translations[typedLocale] ?? {}) as Record<string, unknown>
-      config.i18n.translations[typedLocale] = {
-        ...existing,
-        'plugin-mcp': pluginEntry.translations['plugin-mcp'],
-      } as PluginDefaultTranslationsObject
-    }
-
-    // Keep the API-keys collection registered even when disabled, so DB schema
-    // and generated types don't drift between enabled/disabled environments.
     if (pluginConfig.disabled) {
       return config
     }
 
     return {
       ...config,
-      admin: {
-        ...config.admin,
-        components: {
-          ...config.admin?.components,
-          userMenuSettingsItems: [
-            ...(config.admin?.components?.userMenuSettingsItems ?? []),
-            {
-              group: 'MCP',
-              items: ['@payloadcms/plugin-mcp/client#MCPSettingsMenu'],
-            },
-          ],
-        },
-      },
       endpoints: [
         ...(config.endpoints ?? []),
         // Payload prefixes /api, so the full path is /api/mcp.

package/src/mcp/buildMcpServer.ts

@@ -1,6 +1,7 @@
+import type { PayloadRequest } from 'payload'
+
 import { McpServer, type ServerContext } from '@modelcontextprotocol/server'
-import { APIError, type PayloadRequest } from 'payload'
-import { z } from 'zod'
+import { APIError, strictObject, z } from 'payload'
 
 import type {
   AuthorizedMCP,
@@ -17,10 +18,10 @@ import { getLogger } from '../utils/getLogger.js'
 import { toStandardSchema } from '../utils/toStandardSchema.js'
 
 /**
- * Transport-agnostic core: registers every authorized MCP item onto a fresh
- * `McpServer` and returns it. The caller is responsible for picking a transport
- * (`WebStandardStreamableHTTPServerTransport`, `StdioServerTransport`, …) and
- * calling `server.connect(transport)`.
+ * 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
@@ -35,6 +36,8 @@ export const buildMcpServer = ({
   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 },
@@ -47,18 +50,28 @@ export const buildMcpServer = ({
    * 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 = (
-    response: MCPToolResponse,
-    overrideResponse?: MCPResponseOverride,
-  ): MCPToolResponse => {
-    const overridden = overrideResponse?.(response, response.doc ?? {}, req) ?? response
+  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 `collectionSlug` / `globalSlug` from the input
+   * - 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
    */
@@ -72,16 +85,15 @@ export const buildMcpServer = ({
     serverContext: ServerContext
   }): Promise<MCPToolResponse> => {
     const entity = item.type === 'collectionTool' ? 'collection' : 'global'
-    const slugKey = item.type === 'collectionTool' ? 'collectionSlug' : 'globalSlug'
     const toolInput = (input ?? {}) as Record<string, unknown>
-    const slug = toolInput[slugKey] as string | undefined
+    const slug = toolInput.slug as string | undefined
 
     if (!slug) {
       return {
         content: [
           {
             type: 'text',
-            text: `Error: "${item.mcpName}" requires ${slugKey}. Use getConfigInfo to inspect ${entity} slugs.`,
+            text: `Error: "${item.mcpName}" requires slug. Use getConfigInfo to inspect ${entity} slugs.`,
           },
         ],
         isError: true,
@@ -109,12 +121,22 @@ export const buildMcpServer = ({
       }
     }
 
-    const handlerArgs = { authorizedMCP, input: toolInput, req, serverContext }
+    const handlerArgs = {
+      authorizedMCP,
+      input: toolInput,
+      req,
+      serverContext,
+    }
     const response = await (match.type === 'collectionTool'
-      ? match.tool.handler({ ...handlerArgs, collectionSlug: slug })
-      : match.tool.handler({ ...handlerArgs, globalSlug: slug }))
+      ? match.tool.handler({ ...handlerArgs, slug })
+      : match.tool.handler({ ...handlerArgs, slug }))
 
-    return finalizeToolResponse(response, match.tool.overrideResponse)
+    return finalizeToolResponse({
+      input: toolInput,
+      overrideResponse: match.tool.overrideResponse,
+      response,
+      toolName: match.mcpName,
+    })
   }
 
   try {
@@ -129,10 +151,7 @@ export const buildMcpServer = ({
           }
           registeredEntityTools.add(item.mcpName)
 
-          const inputSchema = withSlugInput({
-            name: item.type === 'collectionTool' ? 'collectionSlug' : 'globalSlug',
-            input: item.tool.input,
-          })
+          const inputSchema = withSlugInput({ input: item.tool.input })
 
           server.registerTool(
             item.mcpName,
@@ -198,16 +217,21 @@ export const buildMcpServer = ({
               description: tool.description,
               inputSchema: tool.input ? toStandardSchema(tool.input) : undefined,
             },
-            async (input: unknown, ctx: ServerContext) =>
-              finalizeToolResponse(
-                await tool.handler({
-                  authorizedMCP,
-                  input: (input ?? {}) as Record<string, unknown>,
-                  req,
-                  serverContext: ctx,
-                }),
-                tool.overrideResponse,
-              ),
+            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
@@ -221,39 +245,50 @@ export const buildMcpServer = ({
   return server
 }
 
-const withSlugInput = ({
-  name,
-  input,
-}: {
-  input?: ToolInputSchema
-  name: 'collectionSlug' | 'globalSlug'
-}): ToolInputSchema => {
-  const description = name === 'collectionSlug' ? 'The collection slug' : 'The global slug'
-  const slugSchema = z.string().describe(description)
+const withSlugInput = ({ input }: { input?: ToolInputSchema }): ToolInputSchema => {
+  const description = 'The target slug.'
+  const slugSchema = z.string().check(z.describe(description))
 
   if (!input) {
-    return z.object({ [name]: slugSchema })
+    return strictObject({ slug: slugSchema }) as unknown as ToolInputSchema
   }
 
-  if (input instanceof z.ZodObject) {
-    return input.extend({ [name]: 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: schema as JsonSchemaType })
   }
 
-  const schema = input as {
+  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 {
-    ...schema,
+    ...objectSchema,
     type: 'object',
     properties: {
-      ...schema.properties,
-      [name]: {
+      ...objectSchema.properties,
+      slug: {
         type: 'string',
         description,
       },
     },
-    required: Array.from(new Set([name, ...(schema.required ?? [])])),
+    required: Array.from(new Set(['slug', ...(objectSchema.required ?? [])])),
   }
 }