@payloadcms/plugin-mcp 3.63.0 → 3.64.0-internal.23abf20

package/src/mcp/getMcpHandler.ts

@@ -4,7 +4,7 @@ import { createMcpHandler } from '@vercel/mcp-adapter'
 import { join } from 'path'
 import { APIError, configToJSONSchema, type PayloadRequest, type TypedUser } from 'payload'
 
-import type { PluginMCPServerConfig, ToolSettings } from '../types.js'
+import type { MCPAccessSettings, PluginMCPServerConfig } from '../types.js'
 
 import { toCamelCase } from '../utils/camelCase.js'
 import { registerTool } from './registerTool.js'
@@ -34,14 +34,14 @@ import { updateJobTool } from './tools/job/update.js'
 
 export const getMCPHandler = (
   pluginOptions: PluginMCPServerConfig,
-  toolSettings: ToolSettings,
+  mcpAccessSettings: MCPAccessSettings,
   req: PayloadRequest,
 ) => {
   const { payload } = req
   const configSchema = configToJSONSchema(payload.config)
 
   // User
-  const user = toolSettings.user as TypedUser
+  const user = mcpAccessSettings.user as TypedUser
 
   // MCP Server and Handler Options
   const MCPOptions = pluginOptions.mcp || {}
@@ -105,7 +105,7 @@ export const getMCPHandler = (
           try {
             const schema = configSchema.definitions?.[enabledCollectionSlug] as JSONSchema4
 
-            const toolCapabilities = toolSettings?.[
+            const toolCapabilities = mcpAccessSettings?.[
               `${toCamelCase(enabledCollectionSlug)}`
             ] as Record<string, unknown>
             const allowCreate: boolean | undefined = toolCapabilities['create'] as boolean
@@ -194,7 +194,7 @@ export const getMCPHandler = (
         // Custom tools
         customMCPTools.forEach((tool) => {
           const camelCasedToolName = toCamelCase(tool.name)
-          const isToolEnabled = toolSettings.custom?.[camelCasedToolName] ?? true
+          const isToolEnabled = mcpAccessSettings['payload-mcp-tool']?.[camelCasedToolName] ?? true
 
           registerTool(
             isToolEnabled,
@@ -207,47 +207,63 @@ export const getMCPHandler = (
 
         // Custom prompts
         customMCPPrompts.forEach((prompt) => {
-          server.registerPrompt(
-            prompt.name,
-            {
-              argsSchema: prompt.argsSchema,
-              description: prompt.description,
-              title: prompt.title,
-            },
-            prompt.handler,
-          )
-          if (useVerboseLogs) {
-            payload.logger.info(`[payload-mcp] ✅ Prompt: ${prompt.title} Registered.`)
+          const camelCasedPromptName = toCamelCase(prompt.name)
+          const isPromptEnabled =
+            mcpAccessSettings['payload-mcp-prompt']?.[camelCasedPromptName] ?? true
+
+          if (isPromptEnabled) {
+            server.registerPrompt(
+              prompt.name,
+              {
+                argsSchema: prompt.argsSchema,
+                description: prompt.description,
+                title: prompt.title,
+              },
+              prompt.handler,
+            )
+            if (useVerboseLogs) {
+              payload.logger.info(`[payload-mcp] ✅ Prompt: ${prompt.title} Registered.`)
+            }
+          } else if (useVerboseLogs) {
+            payload.logger.info(`[payload-mcp] ⏭️ Prompt: ${prompt.title} Skipped.`)
           }
         })
 
         // Custom resources
         customMCPResources.forEach((resource) => {
-          server.registerResource(
-            resource.name,
-            // @ts-expect-error - Overload type is not working however -- ResourceTemplate OR String is a valid type
-            resource.uri,
-            {
-              description: resource.description,
-              mimeType: resource.mimeType,
-              title: resource.title,
-            },
-            resource.handler,
-          )
+          const camelCasedResourceName = toCamelCase(resource.name)
+          const isResourceEnabled =
+            mcpAccessSettings['payload-mcp-resource']?.[camelCasedResourceName] ?? true
+
+          if (isResourceEnabled) {
+            server.registerResource(
+              resource.name,
+              // @ts-expect-error - Overload type is not working however -- ResourceTemplate OR String is a valid type
+              resource.uri,
+              {
+                description: resource.description,
+                mimeType: resource.mimeType,
+                title: resource.title,
+              },
+              resource.handler,
+            )
 
-          if (useVerboseLogs) {
-            payload.logger.info(`[payload-mcp] ✅ Resource: ${resource.title} Registered.`)
+            if (useVerboseLogs) {
+              payload.logger.info(`[payload-mcp] ✅ Resource: ${resource.title} Registered.`)
+            }
+          } else if (useVerboseLogs) {
+            payload.logger.info(`[payload-mcp] ⏭️ Resource: ${resource.title} Skipped.`)
           }
         })
 
         // Experimental - Collection Schema Modfication Tools
         if (
-          toolSettings.collections?.create &&
+          mcpAccessSettings.collections?.create &&
           experimentalTools.collections?.enabled &&
           isDevelopment
         ) {
           registerTool(
-            toolSettings.collections.create,
+            mcpAccessSettings.collections.create,
             'Create Collection',
             () =>
               createCollectionTool(server, req, useVerboseLogs, collectionsDirPath, configFilePath),
@@ -256,12 +272,12 @@ export const getMCPHandler = (
           )
         }
         if (
-          toolSettings.collections?.delete &&
+          mcpAccessSettings.collections?.delete &&
           experimentalTools.collections?.enabled &&
           isDevelopment
         ) {
           registerTool(
-            toolSettings.collections.delete,
+            mcpAccessSettings.collections.delete,
             'Delete Collection',
             () =>
               deleteCollectionTool(server, req, useVerboseLogs, collectionsDirPath, configFilePath),
@@ -271,12 +287,12 @@ export const getMCPHandler = (
         }
 
         if (
-          toolSettings.collections?.find &&
+          mcpAccessSettings.collections?.find &&
           experimentalTools.collections?.enabled &&
           isDevelopment
         ) {
           registerTool(
-            toolSettings.collections.find,
+            mcpAccessSettings.collections.find,
             'Find Collection',
             () => findCollectionTool(server, req, useVerboseLogs, collectionsDirPath),
             payload,
@@ -285,12 +301,12 @@ export const getMCPHandler = (
         }
 
         if (
-          toolSettings.collections?.update &&
+          mcpAccessSettings.collections?.update &&
           experimentalTools.collections?.enabled &&
           isDevelopment
         ) {
           registerTool(
-            toolSettings.collections.update,
+            mcpAccessSettings.collections.update,
             'Update Collection',
             () =>
               updateCollectionTool(server, req, useVerboseLogs, collectionsDirPath, configFilePath),
@@ -300,9 +316,9 @@ export const getMCPHandler = (
         }
 
         // Experimental - Payload Config Modification Tools
-        if (toolSettings.config?.find && experimentalTools.config?.enabled && isDevelopment) {
+        if (mcpAccessSettings.config?.find && experimentalTools.config?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.config.find,
+            mcpAccessSettings.config.find,
             'Find Config',
             () => findConfigTool(server, req, useVerboseLogs, configFilePath),
             payload,
@@ -310,9 +326,13 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.config?.update && experimentalTools.config?.enabled && isDevelopment) {
+        if (
+          mcpAccessSettings.config?.update &&
+          experimentalTools.config?.enabled &&
+          isDevelopment
+        ) {
           registerTool(
-            toolSettings.config.update,
+            mcpAccessSettings.config.update,
             'Update Config',
             () => updateConfigTool(server, req, useVerboseLogs, configFilePath),
             payload,
@@ -321,9 +341,9 @@ export const getMCPHandler = (
         }
 
         // Experimental - Job Modification Tools
-        if (toolSettings.jobs?.create && experimentalTools.jobs?.enabled && isDevelopment) {
+        if (mcpAccessSettings.jobs?.create && experimentalTools.jobs?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.jobs.create,
+            mcpAccessSettings.jobs.create,
             'Create Job',
             () => createJobTool(server, req, useVerboseLogs, jobsDirPath),
             payload,
@@ -331,9 +351,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.jobs?.update && experimentalTools.jobs?.enabled && isDevelopment) {
+        if (mcpAccessSettings.jobs?.update && experimentalTools.jobs?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.jobs.update,
+            mcpAccessSettings.jobs.update,
             'Update Job',
             () => updateJobTool(server, req, useVerboseLogs, jobsDirPath),
             payload,
@@ -341,9 +361,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.jobs?.run && experimentalTools.jobs?.enabled && isDevelopment) {
+        if (mcpAccessSettings.jobs?.run && experimentalTools.jobs?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.jobs.run,
+            mcpAccessSettings.jobs.run,
             'Run Job',
             () => runJobTool(server, req, useVerboseLogs),
             payload,
@@ -352,9 +372,9 @@ export const getMCPHandler = (
         }
 
         // Experimental - Auth Modification Tools
-        if (toolSettings.auth?.auth && experimentalTools.auth?.enabled && isDevelopment) {
+        if (mcpAccessSettings.auth?.auth && experimentalTools.auth?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.auth.auth,
+            mcpAccessSettings.auth.auth,
             'Auth',
             () => authTool(server, req, useVerboseLogs),
             payload,
@@ -362,9 +382,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.auth?.login && experimentalTools.auth?.enabled && isDevelopment) {
+        if (mcpAccessSettings.auth?.login && experimentalTools.auth?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.auth.login,
+            mcpAccessSettings.auth.login,
             'Login',
             () => loginTool(server, req, useVerboseLogs),
             payload,
@@ -372,9 +392,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.auth?.verify && experimentalTools.auth?.enabled && isDevelopment) {
+        if (mcpAccessSettings.auth?.verify && experimentalTools.auth?.enabled && isDevelopment) {
           registerTool(
-            toolSettings.auth.verify,
+            mcpAccessSettings.auth.verify,
             'Verify',
             () => verifyTool(server, req, useVerboseLogs),
             payload,
@@ -382,9 +402,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.auth?.resetPassword && experimentalTools.auth?.enabled) {
+        if (mcpAccessSettings.auth?.resetPassword && experimentalTools.auth?.enabled) {
           registerTool(
-            toolSettings.auth.resetPassword,
+            mcpAccessSettings.auth.resetPassword,
             'Reset Password',
             () => resetPasswordTool(server, req, useVerboseLogs),
             payload,
@@ -392,9 +412,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.auth?.forgotPassword && experimentalTools.auth?.enabled) {
+        if (mcpAccessSettings.auth?.forgotPassword && experimentalTools.auth?.enabled) {
           registerTool(
-            toolSettings.auth.forgotPassword,
+            mcpAccessSettings.auth.forgotPassword,
             'Forgot Password',
             () => forgotPasswordTool(server, req, useVerboseLogs),
             payload,
@@ -402,9 +422,9 @@ export const getMCPHandler = (
           )
         }
 
-        if (toolSettings.auth?.unlock && experimentalTools.auth?.enabled) {
+        if (mcpAccessSettings.auth?.unlock && experimentalTools.auth?.enabled) {
           registerTool(
-            toolSettings.auth.unlock,
+            mcpAccessSettings.auth.unlock,
             'Unlock',
             () => unlockTool(server, req, useVerboseLogs),
             payload,

package/src/mcp/tools/resource/create.ts

@@ -52,6 +52,7 @@ export const createResourceTool = (
         collection: collectionSlug,
         // TODO: Move the override to a `beforeChange` hook and extend the payloadAPI context req to include MCP request info.
         data: collections?.[collectionSlug]?.override?.(parsedData, req) || parsedData,
+        overrideAccess: false,
         user,
       })
 
@@ -110,7 +111,7 @@ ${JSON.stringify(result, null, 2)}
 
     server.tool(
       `create${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${toolSchemas.createResource.description.trim()}\n\n${collections?.[collectionSlug]?.description || ''}`,
+      `${collections?.[collectionSlug]?.description || toolSchemas.createResource.description.trim()}`,
       convertedFields.shape,
       async (params: Record<string, unknown>) => {
         const data = JSON.stringify(params)

package/src/mcp/tools/resource/delete.ts

@@ -77,6 +77,7 @@ export const deleteResourceTool = (
       const deleteOptions: Record<string, unknown> = {
         collection: collectionSlug,
         depth,
+        overrideAccess: false,
         user,
       }
 
@@ -200,7 +201,7 @@ ${JSON.stringify(errors, null, 2)}
   if (collections?.[collectionSlug]?.enabled) {
     server.tool(
       `delete${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${toolSchemas.deleteResource.description.trim()}\n\n${collections?.[collectionSlug]?.description || ''}`,
+      `${collections?.[collectionSlug]?.description || toolSchemas.deleteResource.description.trim()}`,
       toolSchemas.deleteResource.parameters.shape,
       async ({ id, depth, where }) => {
         return await tool(id, where, depth)

package/src/mcp/tools/resource/find.ts

@@ -64,6 +64,7 @@ export const findResourceTool = (
           const doc = await payload.findByID({
             id,
             collection: collectionSlug,
+            overrideAccess: false,
             user,
           })
 
@@ -114,6 +115,7 @@ ${JSON.stringify(doc, null, 2)}`,
       const findOptions: Parameters<typeof payload.find>[0] = {
         collection: collectionSlug,
         limit,
+        overrideAccess: false,
         page,
         user,
       }
@@ -184,7 +186,7 @@ Page: ${result.page} of ${result.totalPages}
   if (collections?.[collectionSlug]?.enabled) {
     server.tool(
       `find${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${toolSchemas.findResources.description.trim()}\n\n${collections?.[collectionSlug]?.description || ''}`,
+      `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
       toolSchemas.findResources.parameters.shape,
       async ({ id, limit, page, sort, where }) => {
         return await tool(id, limit, page, sort, where)

package/src/mcp/tools/resource/update.ts

@@ -114,6 +114,7 @@ export const updateResourceTool = (
           data: parsedData,
           depth,
           draft,
+          overrideAccess: false,
           overrideLock,
           user,
           ...(filePath && { filePath }),
@@ -159,8 +160,9 @@ ${JSON.stringify(result, null, 2)}
           data: parsedData,
           depth,
           draft,
-          overrideAccess: true,
+          overrideAccess: false,
           overrideLock,
+          user,
           where: whereClause,
           ...(filePath && { filePath }),
           ...(overwriteExistingFiles && { overwriteExistingFiles }),
@@ -283,7 +285,7 @@ ${JSON.stringify(errors, null, 2)}
 
     server.tool(
       `update${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${toolSchemas.updateResource.description.trim()}\n\n${collections?.[collectionSlug]?.description || ''}`,
+      `${collections?.[collectionSlug]?.description || toolSchemas.updateResource.description.trim()}`,
       updateResourceSchema.shape,
       async (params: Record<string, unknown>) => {
         const {

package/src/mcp/tools/schemas.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 
 export const toolSchemas = {
   findResources: {
-    description: 'Find documents in a Payload collection using Find or FindByID.',
+    description: 'Find documents in a collection by ID or where clause using Find or FindByID.',
     parameters: z.object({
       id: z
         .string()
@@ -39,7 +39,7 @@ export const toolSchemas = {
   },
 
   createResource: {
-    description: 'Create a document in a Payload collection.',
+    description: 'Create a document in a collection.',
     parameters: z.object({
       data: z.string().describe('JSON string containing the data for the new document'),
       draft: z
@@ -51,7 +51,7 @@ export const toolSchemas = {
   },
 
   updateResource: {
-    description: 'Update documents in a Payload collection by ID or where clause.',
+    description: 'Update documents in a collection by ID or where clause.',
     parameters: z.object({
       id: z.string().optional().describe('Optional: specific document ID to update'),
       data: z.string().describe('JSON string containing the data to update'),
@@ -83,7 +83,7 @@ export const toolSchemas = {
   },
 
   deleteResource: {
-    description: 'Delete documents in a Payload collection by ID or where clause.',
+    description: 'Delete documents in a collection by ID or where clause.',
     parameters: z.object({
       id: z.string().optional().describe('Optional: specific document ID to delete'),
       depth: z
@@ -103,7 +103,7 @@ export const toolSchemas = {
 
   // Experimental Below This Line
   createCollection: {
-    description: 'Creates a new Payload collection with specified fields and configuration.',
+    description: 'Creates a new collection with specified fields and configuration.',
     parameters: z.object({
       collectionDescription: z
         .string()
@@ -119,7 +119,7 @@ export const toolSchemas = {
   },
 
   findCollections: {
-    description: 'Finds and lists Payload collections with optional content and document counts.',
+    description: 'Finds and lists collections with optional content and document counts.',
     parameters: z.object({
       collectionName: z
         .string()
@@ -140,7 +140,7 @@ export const toolSchemas = {
 
   updateCollection: {
     description:
-      'Updates an existing Payload collection with new fields, modifications, or configuration changes.',
+      'Updates an existing collection with new fields, modifications, or configuration changes.',
     parameters: z.object({
       collectionName: z.string().describe('The name of the collection to update'),
       configUpdates: z.any().optional().describe('Configuration updates (for update_config type)'),
@@ -164,7 +164,7 @@ export const toolSchemas = {
   },
 
   deleteCollection: {
-    description: 'Deletes a Payload collection and optionally updates the configuration.',
+    description: 'Deletes a collection and optionally updates the configuration.',
     parameters: z.object({
       collectionName: z.string().describe('The name of the collection to delete'),
       confirmDeletion: z.boolean().describe('Confirmation flag to prevent accidental deletion'),
@@ -177,7 +177,7 @@ export const toolSchemas = {
   },
 
   findConfig: {
-    description: 'Reads and displays the current Payload configuration file.',
+    description: 'Reads and displays the current configuration file.',
     parameters: z.object({
       includeMetadata: z
         .boolean()
@@ -188,7 +188,7 @@ export const toolSchemas = {
   },
 
   updateConfig: {
-    description: 'Updates the Payload configuration file with various modifications.',
+    description: 'Updates the configuration file with various modifications.',
     parameters: z.object({
       adminConfig: z
         .any()
@@ -302,7 +302,7 @@ export const toolSchemas = {
   },
 
   createJob: {
-    description: 'Creates a new Payload job (task or workflow) with specified configuration.',
+    description: 'Creates a new job (task or workflow) with specified configuration.',
     parameters: z.object({
       description: z.string().describe('Description of what the job does'),
       inputSchema: z.record(z.any()).optional().default({}).describe('Input schema for the job'),
@@ -329,7 +329,7 @@ export const toolSchemas = {
   },
 
   updateJob: {
-    description: 'Updates an existing Payload job with new configuration, schema, or handler code.',
+    description: 'Updates an existing job with new configuration, schema, or handler code.',
     parameters: z.object({
       configUpdate: z.record(z.any()).optional().describe('New configuration for the job'),
       handlerCode: z
@@ -347,7 +347,7 @@ export const toolSchemas = {
   },
 
   runJob: {
-    description: 'Runs a Payload job with specified input data and queue options.',
+    description: 'Runs a job with specified input data and queue options.',
     parameters: z.object({
       delay: z
         .number()

package/src/types.ts

@@ -14,7 +14,7 @@ export type PluginMCPServerConfig = {
         /**
          * Set the description of the collection. This is used by MCP clients to determine when to use the collecton as a resource.
          */
-        description: string
+        description?: string
         /**
          * Set the enabled capabilities of the collection. Admins can then allow or disallow the use of the capability by MCP clients.
          */
@@ -26,7 +26,6 @@ export type PluginMCPServerConfig = {
               update?: boolean
             }
           | boolean
-
         /**
          * Override the data generated by the MCP client. This allows you to modify the data that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
          */
@@ -217,6 +216,11 @@ export type PluginMCPServerConfig = {
     }[]
   }
   overrideApiKeyCollection?: (collection: CollectionConfig) => CollectionConfig
+
+  /**
+   * Set the users collection that API keys should be associated with.
+   */
+  userCollection?: CollectionConfig | string
 }
 
 /**
@@ -267,7 +271,7 @@ export type MCPServerOptions = {
   }
 }
 
-export type ToolSettings = {
+export type MCPAccessSettings = {
   auth?: {
     auth?: boolean
     forgotPassword?: boolean
@@ -286,12 +290,14 @@ export type ToolSettings = {
     find?: boolean
     update?: boolean
   }
-  custom?: Record<string, boolean>
   jobs?: {
     create?: boolean
     run?: boolean
     update?: boolean
   }
+  'payload-mcp-prompt'?: Record<string, boolean>
+  'payload-mcp-resource'?: Record<string, boolean>
+  'payload-mcp-tool'?: Record<string, boolean>
 } & Record<string, unknown>
 
 export type FieldDefinition = {