@payloadcms/plugin-mcp 4.0.0-internal.4cbdd50 → 4.0.0-internal.4e1f822

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'
@@ -27,22 +33,45 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
   }
 
   const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
+  // Payload augments the original web-standard Request in place.
+  const mcpRequest = req as PayloadRequest & Request
 
-  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
-
-  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)) {
+    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' })
+    }
 
-  await server.connect(transport)
+    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 mcpRequest = new Request(req.url, {
-    body: req.body,
-    duplex: 'half',
-    headers: req.headers,
-    method: req.method,
-  } as { duplex: 'half' } & RequestInit)
+  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',
+  })
 
-  return await transport.handleRequest(mcpRequest)
+  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/index.ts

@@ -6,8 +6,8 @@ import { mcpEndpoint } from './endpoint/index.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. */
@@ -22,8 +22,8 @@ export { defineCollectionTool, defineGlobalTool, definePrompt, defineTool } from
 export const mcpPlugin = definePlugin<MCPPluginConfig>({
   slug: '@payloadcms/plugin-mcp',
   order: 10,
-  plugin: ({ config, plugins, ...rawConfig }) => {
-    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']

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,
@@ -16,11 +17,13 @@ import type {
 import { getLogger } from '../utils/getLogger.js'
 import { toStandardSchema } from '../utils/toStandardSchema.js'
 
+z.config(z.locales.en())
+
 /**
- * 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
@@ -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,
@@ -116,10 +128,15 @@ export const buildMcpServer = ({
       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 {
@@ -134,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,
@@ -203,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
@@ -226,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 ?? [])])),
   }
 }

package/src/mcp/builtin/collections/authTools.ts

@@ -1,7 +1,8 @@
-import { z } from 'zod'
+import { createLocalReq, strictObject, z } from 'payload'
 
 import type { MCPToolResponse } from '../../../types.js'
 
+import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
 
@@ -16,16 +17,16 @@ import { getLogger } from '../../../utils/getLogger.js'
  * users collection so all auth-shaped tools live in one place.
  */
 
-const emailSchema = z.string().email().describe('The user email address')
+const emailSchema = z.email().check(z.describe('The user email address.'))
 
 const wrapError =
   (name: string) =>
-  ({ collectionSlug, message }: { collectionSlug: string; message: string }): MCPToolResponse => {
+  ({ slug, message }: { message: string; slug: string }): MCPToolResponse => {
     return {
       content: [
         {
           type: 'text',
-          text: `❌ **Error in ${name}** on ${collectionSlug}: ${message}`,
+          text: `❌ **Error in ${name}** on ${slug}: ${message}`,
         },
       ],
     }
@@ -40,20 +41,38 @@ export const authCollectionTool = defineCollectionTool({
     title: 'Check Auth Status',
   },
   description: 'Checks authentication status for the current user.',
-  input: z.object({
+  input: strictObject({
     headers: z
-      .record(z.string(), z.string())
-      .describe('Optional custom headers to send with the authentication request')
-      .optional(),
+      .optional(z.record(z.string(), z.string()))
+      .check(z.describe('Custom headers to send with the authentication request.')),
   }),
-}).handler(async ({ collectionSlug, input, req }) => {
+}).handler(async ({ slug, authorizedMCP, input, req }) => {
   const logger = getLogger({ payload: req.payload })
   try {
     let authHeaders = new Headers()
     if (input.headers) {
       authHeaders = new Headers(input.headers)
     }
-    const result = await req.payload.auth({ headers: authHeaders })
+    const authReq = await createLocalReq({ req: { headers: authHeaders } }, req.payload)
+    const result = await req.payload.auth({ headers: authHeaders, req: authReq })
+
+    if (result.user) {
+      const authenticatedUser = result.user
+      // Auth strategies read users with trusted Local API access. Re-read the user with the MCP
+      // caller's access level before returning it to the client.
+      const user = await req.payload.findByID({
+        id: authenticatedUser.id,
+        collection: authenticatedUser.collection,
+        overrideAccess: authorizedMCP.overrideAccess,
+        req: authReq,
+      })
+      result.user = {
+        ...user,
+        _sid: authenticatedUser._sid,
+        _strategy: authenticatedUser._strategy,
+        collection: authenticatedUser.collection,
+      }
+    }
     return {
       content: [
         {
@@ -65,8 +84,8 @@ export const authCollectionTool = defineCollectionTool({
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error in auth tool on ${collectionSlug}: ${errorMessage}`)
-    return wrapError('auth')({ collectionSlug, message: errorMessage })
+    logger.error(`Error in auth tool on ${slug}: ${errorMessage}`)
+    return wrapError('auth')({ slug, message: errorMessage })
   }
 })
 
@@ -79,35 +98,31 @@ export const forgotPasswordCollectionTool = defineCollectionTool({
     title: 'Forgot Password',
   },
   description: 'Sends a password reset email to a user.',
-  input: z.object({
-    disableEmail: z
-      .boolean()
-      .describe('Whether to disable sending the email (for testing)')
-      .optional()
-      .default(false),
+  input: strictObject({
     email: emailSchema,
   }),
-}).handler(async ({ collectionSlug, input, req }) => {
+}).handler(async ({ slug, input, req }) => {
   const logger = getLogger({ payload: req.payload })
   try {
-    const result = await req.payload.forgotPassword({
-      collection: collectionSlug,
+    await req.payload.forgotPassword({
+      collection: slug,
       data: { email: input.email },
-      disableEmail: input.disableEmail,
+      disableEmail: false,
+      overrideAccess: false,
+      req,
     })
     return {
       content: [
         {
           type: 'text',
-          text: `# Forgot Password Email Sent\n\n**Collection:** ${collectionSlug}\n**Email:** ${input.email}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+          text: 'If an account matches that email, password reset instructions have been sent.',
         },
       ],
-      doc: { result } as Record<string, unknown>,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error in forgotPassword tool on ${collectionSlug}: ${errorMessage}`)
-    return wrapError('forgotPassword')({ collectionSlug, message: errorMessage })
+    logger.error(`Error in forgotPassword tool on ${slug}: ${errorMessage}`)
+    return wrapError('forgotPassword')({ slug, message: errorMessage })
   }
 })
 
@@ -120,45 +135,35 @@ export const loginCollectionTool = defineCollectionTool({
     title: 'User Login',
   },
   description: 'Authenticates a user with email and password.',
-  input: z.object({
+  input: strictObject({
     depth: z
-      .number()
-      .int()
-      .min(0)
-      .max(10)
-      .describe('Depth of population for relationships')
-      .optional()
-      .default(0),
+      ._default(z.int().check(z.minimum(0), z.maximum(10)), 0)
+      .check(z.describe('Depth of population for relationships.')),
     email: emailSchema,
-    password: z.string().describe('The user password'),
-    showHiddenFields: z
-      .boolean()
-      .describe('Whether to show hidden fields in the response')
-      .optional()
-      .default(false),
+    password: z.string().check(z.describe('The user password.')),
   }),
-}).handler(async ({ collectionSlug, input, req }) => {
+}).handler(async ({ slug, authorizedMCP, input, req }) => {
   const logger = getLogger({ payload: req.payload })
   try {
     const result = await req.payload.login({
-      collection: collectionSlug,
+      collection: slug,
       data: { email: input.email, password: input.password },
       depth: input.depth,
-      showHiddenFields: input.showHiddenFields,
+      overrideAccess: authorizedMCP.overrideAccess,
     })
     return {
       content: [
         {
           type: 'text',
-          text: `# Login Successful\n\n**User:** ${input.email}\n**Collection:** ${collectionSlug}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+          text: `# Login Successful\n\n**User:** ${input.email}\n**Collection:** ${slug}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
         },
       ],
       doc: result as unknown as Record<string, unknown>,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error in login tool on ${collectionSlug}: ${errorMessage}`)
-    return wrapError('login')({ collectionSlug, message: errorMessage })
+    logger.error(`Error in login tool on ${slug}: ${errorMessage}`)
+    return wrapError('login')({ slug, message: errorMessage })
   }
 })
 
@@ -171,35 +176,37 @@ export const resetPasswordCollectionTool = defineCollectionTool({
     title: 'Reset Password',
   },
   description: 'Resets a user password with a reset token.',
-  input: z.object({
-    password: z.string().describe('The new password for the user'),
-    token: z.string().describe('The password reset token sent to the user email'),
+  input: strictObject({
+    password: z.string().check(z.describe('The new password for the user.')),
+    token: z.string().check(z.describe('The password reset token sent to the user email.')),
   }),
-}).handler(async ({ collectionSlug, input, req }) => {
+}).handler(async ({ slug, authorizedMCP, input, req }) => {
   const logger = getLogger({ payload: req.payload })
   try {
     const result = await req.payload.resetPassword({
-      collection: collectionSlug,
+      collection: slug,
       data: { password: input.password, token: input.token },
-      overrideAccess: true,
+      overrideAccess: authorizedMCP.overrideAccess,
     })
     return {
       content: [
         {
           type: 'text',
-          text: `# Password Reset Successful\n\n**Collection:** ${collectionSlug}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+          text: `# Password Reset Successful\n\n**Collection:** ${slug}\n\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
         },
       ],
       doc: result as unknown as Record<string, unknown>,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error in resetPassword tool on ${collectionSlug}: ${errorMessage}`)
-    return wrapError('resetPassword')({ collectionSlug, message: errorMessage })
+    logger.error(`Error in resetPassword tool on ${slug}: ${errorMessage}`)
+    return wrapError('resetPassword')({ slug, message: errorMessage })
   }
 })
 
 export const unlockCollectionTool = defineCollectionTool({
+  access: (args) =>
+    defaultAccess(args) && Boolean(args.permissions?.collections?.[args.slug]?.unlock),
   annotations: {
     destructiveHint: false,
     idempotentHint: true,
@@ -208,28 +215,29 @@ export const unlockCollectionTool = defineCollectionTool({
     title: 'Unlock Account',
   },
   description: 'Unlocks a user account that has been locked due to failed login attempts.',
-  input: z.object({ email: emailSchema }),
-}).handler(async ({ collectionSlug, input, req }) => {
+  input: strictObject({ email: emailSchema }),
+}).handler(async ({ slug, authorizedMCP, input, req }) => {
   const logger = getLogger({ payload: req.payload })
   try {
     const result = await req.payload.unlock({
-      collection: collectionSlug,
+      collection: slug,
       data: { email: input.email },
-      overrideAccess: true,
+      overrideAccess: authorizedMCP.overrideAccess,
+      req,
     })
     return {
       content: [
         {
           type: 'text',
-          text: `# Account Unlocked\n\n**Collection:** ${collectionSlug}\n**Email:** ${input.email}\n**Result:** ${result ? 'Success' : 'Failed'}`,
+          text: `# Account Unlocked\n\n**Collection:** ${slug}\n**Email:** ${input.email}\n**Result:** ${result ? 'Success' : 'Failed'}`,
         },
       ],
       doc: { result } as Record<string, unknown>,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error in unlock tool on ${collectionSlug}: ${errorMessage}`)
-    return wrapError('unlock')({ collectionSlug, message: errorMessage })
+    logger.error(`Error in unlock tool on ${slug}: ${errorMessage}`)
+    return wrapError('unlock')({ slug, message: errorMessage })
   }
 })
 
@@ -242,28 +250,28 @@ export const verifyCollectionTool = defineCollectionTool({
     title: 'Email Verification',
   },
   description: 'Verifies a user email with a verification token.',
-  input: z.object({
-    token: z.string().describe('The verification token sent to the user email'),
+  input: strictObject({
+    token: z.string().check(z.describe('The verification token sent to the user email.')),
   }),
-}).handler(async ({ collectionSlug, input, req }) => {
+}).handler(async ({ slug, input, req }) => {
   const logger = getLogger({ payload: req.payload })
   try {
     const result = await req.payload.verifyEmail({
-      collection: collectionSlug,
+      collection: slug,
       token: input.token,
     })
     return {
       content: [
         {
           type: 'text',
-          text: `# Email Verification Successful\n\n**Collection:** ${collectionSlug}\n**Result:** ${result ? 'Success' : 'Failed'}`,
+          text: `# Email Verification Successful\n\n**Collection:** ${slug}\n**Result:** ${result ? 'Success' : 'Failed'}`,
         },
       ],
       doc: { result } as Record<string, unknown>,
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error in verify tool on ${collectionSlug}: ${errorMessage}`)
-    return wrapError('verify')({ collectionSlug, message: errorMessage })
+    logger.error(`Error in verify tool on ${slug}: ${errorMessage}`)
+    return wrapError('verify')({ slug, message: errorMessage })
   }
 })