@payloadcms/plugin-mcp 4.0.0-internal.cc18726 → 4.0.0-internal.cd47d20

package/dist/stdio.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/stdio.ts"],"sourcesContent":["import type { Config, Plugin, SanitizedConfig } from 'payload'\n\n/* eslint-disable no-console */\nimport { serveStdio } from '@modelcontextprotocol/server/stdio'\nimport { fileURLToPath, pathToFileURL } from 'node:url'\nimport { createLocalReq, getPayload } from 'payload'\nimport { findConfig, loadEnv } from 'payload/node'\n\nimport type { SanitizedMCPPluginConfig } from './types.js'\n\nimport { getAuthorizedMCP } from './endpoint/access.js'\nimport { buildMcpServer } from './mcp/buildMcpServer.js'\nimport { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'\nimport { getPluginConfig } from './utils/getPluginConfig.js'\nimport { resolveProjectRoot } from './utils/resolveProjectRoot.js'\n\n/**\n * Starts Payload's MCP server over stdin and stdout.\n *\n * Set `PAYLOAD_MCP_AUTHORIZATION` to authenticate. In development,\n * `PAYLOAD_MCP_OVERRIDE_ACCESS=true` skips access checks.\n */\nexport const runMcpStdio = async (): Promise<void> => {\n  // MCP clients may start this command from another folder. Move to the Payload\n  // project so findConfig() can find the config.\n  const projectRoot = resolveProjectRoot(fileURLToPath(import.meta.url))\n  if (projectRoot) {\n    process.chdir(projectRoot)\n  }\n\n  loadEnv()\n  const configPath = findConfig()\n  const configModule = await import(pathToFileURL(configPath).toString())\n  const config = (await (configModule.default ?? configModule)) as SanitizedConfig\n\n  /**\n   * stdout is only for MCP messages. The spec says the server must not write\n   * logs there and may write them to stderr instead.\n   *\n   * The 2.0 client library recovers from stray stdout logs, but that behavior is not\n   * guaranteed. Move Payload logs to stderr so Payload does not add invalid data\n   * to stdout. Keep options from configurable loggers. Replace pre-built loggers\n   * because their output cannot be redirected.\n   *\n   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio\n   */\n  const loggerConfig: { logger?: Config['logger'] } = config\n  if (\n    loggerConfig.logger &&\n    typeof loggerConfig.logger === 'object' &&\n    'options' in loggerConfig.logger\n  ) {\n    loggerConfig.logger.destination = process.stderr\n  } else {\n    loggerConfig.logger = { destination: process.stderr, options: {} }\n  }\n\n  const payload = await getPayload({ config, cron: false, disableOnInit: true })\n\n  let pluginConfig: SanitizedMCPPluginConfig\n  try {\n    pluginConfig = getPluginConfig({ config: payload.config })\n  } catch {\n    // The command also works when mcpPlugin() is not in the Payload config.\n    pluginConfig = sanitizeMCPConfig({ config: payload.config, pluginConfig: {} })\n\n    const fallbackPlugin: Plugin = (config) => config\n    Object.assign(fallbackPlugin, {\n      slug: '@payloadcms/plugin-mcp',\n      sanitizedOptions: pluginConfig,\n    })\n    payload.config.plugins ??= []\n    payload.config.plugins.push(fallbackPlugin)\n  }\n\n  const overrideAccessEnv = process.env.PAYLOAD_MCP_OVERRIDE_ACCESS\n  let overrideAccess = false\n\n  if (overrideAccessEnv === 'true') {\n    overrideAccess = true\n  } else if (overrideAccessEnv && overrideAccessEnv !== 'false') {\n    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS must be \"true\" or \"false\".')\n  }\n\n  if (overrideAccess && process.env.NODE_ENV !== 'development') {\n    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS is only available in development.')\n  }\n\n  const headers = new Headers()\n  if (process.env.PAYLOAD_MCP_AUTHORIZATION) {\n    headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)\n  }\n\n  const req = await createLocalReq({ req: { headers } }, payload)\n  req.payloadAPI = 'MCP' as const\n  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })\n\n  const stdioServer = serveStdio(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {\n    onerror: (err) => {\n      // MCP messages use stdout, so write SDK errors to stderr.\n      console.error('[payload-mcp] error serving MCP over stdio:', err)\n    },\n  })\n\n  // Close the MCP server and Payload when the client disconnects or the process stops.\n  let isShuttingDown = false\n  const shutdown = async () => {\n    if (isShuttingDown) {\n      return\n    }\n    isShuttingDown = true\n\n    try {\n      await stdioServer.close()\n    } catch (err) {\n      console.error('[payload-mcp] error closing server:', err)\n    }\n\n    try {\n      await payload.destroy()\n    } catch (err) {\n      console.error('[payload-mcp] error destroying payload:', err)\n    }\n\n    process.exit(0)\n  }\n\n  process.once('SIGINT', () => void shutdown())\n  process.once('SIGTERM', () => void shutdown())\n  process.stdin.once('close', () => void shutdown())\n}\n"],"names":["serveStdio","fileURLToPath","pathToFileURL","createLocalReq","getPayload","findConfig","loadEnv","getAuthorizedMCP","buildMcpServer","sanitizeMCPConfig","getPluginConfig","resolveProjectRoot","runMcpStdio","projectRoot","url","process","chdir","configPath","configModule","toString","config","default","loggerConfig","logger","destination","stderr","options","payload","cron","disableOnInit","pluginConfig","fallbackPlugin","Object","assign","slug","sanitizedOptions","plugins","push","overrideAccessEnv","env","PAYLOAD_MCP_OVERRIDE_ACCESS","overrideAccess","Error","NODE_ENV","headers","Headers","PAYLOAD_MCP_AUTHORIZATION","set","req","payloadAPI","authorizedMCP","stdioServer","onerror","err","console","error","isShuttingDown","shutdown","close","destroy","exit","once","stdin"],"mappings":"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"}
+{"version":3,"sources":["../src/stdio.ts"],"sourcesContent":["import type { Config, Plugin, SanitizedConfig } from 'payload'\n\n/* eslint-disable no-console */\nimport { serveStdio } from '@modelcontextprotocol/server/stdio'\nimport { fileURLToPath, pathToFileURL } from 'node:url'\nimport { createPayloadRequest, getPayload } from 'payload'\nimport { findConfig, loadEnv } from 'payload/node'\n\nimport type { SanitizedMCPPluginConfig } from './types.js'\n\nimport { getAuthorizedMCP } from './endpoint/access.js'\nimport { buildMcpServer } from './mcp/buildMcpServer.js'\nimport { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'\nimport { getPluginConfig } from './utils/getPluginConfig.js'\nimport { resolveProjectRoot } from './utils/resolveProjectRoot.js'\n\n/**\n * Starts Payload's MCP server over stdin and stdout.\n *\n * Set `PAYLOAD_MCP_AUTHORIZATION` to authenticate. In development,\n * `PAYLOAD_MCP_OVERRIDE_ACCESS=true` skips access checks.\n */\nexport const runMcpStdio = async (): Promise<void> => {\n  // MCP clients may start this command from another folder. Move to the Payload\n  // project so findConfig() can find the config.\n  const projectRoot = resolveProjectRoot(fileURLToPath(import.meta.url))\n  if (projectRoot) {\n    process.chdir(projectRoot)\n  }\n\n  loadEnv()\n  const configPath = findConfig()\n  const configModule = await import(pathToFileURL(configPath).toString())\n  const config = (await (configModule.default ?? configModule)) as SanitizedConfig\n\n  /**\n   * stdout is only for MCP messages. The spec says the server must not write\n   * logs there and may write them to stderr instead.\n   *\n   * The 2.0 client library recovers from stray stdout logs, but that behavior is not\n   * guaranteed. Move Payload logs to stderr so Payload does not add invalid data\n   * to stdout. Keep options from configurable loggers. Replace pre-built loggers\n   * because their output cannot be redirected.\n   *\n   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio\n   */\n  const loggerConfig: { logger?: Config['logger'] } = config\n  if (\n    loggerConfig.logger &&\n    typeof loggerConfig.logger === 'object' &&\n    'options' in loggerConfig.logger\n  ) {\n    loggerConfig.logger.destination = process.stderr\n  } else {\n    loggerConfig.logger = { destination: process.stderr, options: {} }\n  }\n\n  const payload = await getPayload({ config, cron: false, disableOnInit: true })\n\n  let pluginConfig: SanitizedMCPPluginConfig\n  try {\n    pluginConfig = getPluginConfig({ config: payload.config })\n  } catch {\n    // The command also works when mcpPlugin() is not in the Payload config.\n    pluginConfig = sanitizeMCPConfig({ config: payload.config, pluginConfig: {} })\n\n    const fallbackPlugin: Plugin = (config) => config\n    Object.assign(fallbackPlugin, {\n      slug: '@payloadcms/plugin-mcp',\n      sanitizedOptions: pluginConfig,\n    })\n    payload.config.plugins ??= []\n    payload.config.plugins.push(fallbackPlugin)\n  }\n\n  const overrideAccessEnv = process.env.PAYLOAD_MCP_OVERRIDE_ACCESS\n  let overrideAccess = false\n\n  if (overrideAccessEnv === 'true') {\n    overrideAccess = true\n  } else if (overrideAccessEnv && overrideAccessEnv !== 'false') {\n    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS must be \"true\" or \"false\".')\n  }\n\n  if (overrideAccess && process.env.NODE_ENV !== 'development') {\n    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS is only available in development.')\n  }\n\n  const headers = new Headers()\n  if (process.env.PAYLOAD_MCP_AUTHORIZATION) {\n    headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)\n  }\n\n  const req = await createPayloadRequest({ payload, req: { headers } })\n  req.payloadAPI = 'MCP' as const\n  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })\n\n  const stdioServer = serveStdio(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {\n    onerror: (err) => {\n      // MCP messages use stdout, so write SDK errors to stderr.\n      console.error('[payload-mcp] error serving MCP over stdio:', err)\n    },\n  })\n\n  // Close the MCP server and Payload when the client disconnects or the process stops.\n  let isShuttingDown = false\n  const shutdown = async () => {\n    if (isShuttingDown) {\n      return\n    }\n    isShuttingDown = true\n\n    try {\n      await stdioServer.close()\n    } catch (err) {\n      console.error('[payload-mcp] error closing server:', err)\n    }\n\n    try {\n      await payload.destroy()\n    } catch (err) {\n      console.error('[payload-mcp] error destroying payload:', err)\n    }\n\n    process.exit(0)\n  }\n\n  process.once('SIGINT', () => void shutdown())\n  process.once('SIGTERM', () => void shutdown())\n  process.stdin.once('close', () => void shutdown())\n}\n"],"names":["serveStdio","fileURLToPath","pathToFileURL","createPayloadRequest","getPayload","findConfig","loadEnv","getAuthorizedMCP","buildMcpServer","sanitizeMCPConfig","getPluginConfig","resolveProjectRoot","runMcpStdio","projectRoot","url","process","chdir","configPath","configModule","toString","config","default","loggerConfig","logger","destination","stderr","options","payload","cron","disableOnInit","pluginConfig","fallbackPlugin","Object","assign","slug","sanitizedOptions","plugins","push","overrideAccessEnv","env","PAYLOAD_MCP_OVERRIDE_ACCESS","overrideAccess","Error","NODE_ENV","headers","Headers","PAYLOAD_MCP_AUTHORIZATION","set","req","payloadAPI","authorizedMCP","stdioServer","onerror","err","console","error","isShuttingDown","shutdown","close","destroy","exit","once","stdin"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-internal.cc18726",
+  "version": "4.0.0-internal.cd47d20",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
     "plugin",
@@ -60,10 +60,10 @@
   },
   "devDependencies": {
     "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-internal.cc18726"
+    "payload": "4.0.0-internal.cd47d20"
   },
   "peerDependencies": {
-    "payload": "4.0.0-internal.cc18726"
+    "payload": "4.0.0-internal.cd47d20"
   },
   "//deps_notes": {
     "tsx": "Required by the `bin.js` stdio mcp. Keep the version pinned to whatever `payload` ships to avoid duplicate installs."
@@ -75,7 +75,7 @@
     "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
     "clean": "rimraf {dist,*.tsbuildinfo}",
-    "copyfiles": "copyfiles -u 1 \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
+    "copyfiles": "copyfiles -u 1 -e \"**/*.spec.*\" \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "pack:plugin": "pnpm build && pnpm pack"

package/src/mcp/buildMcpServer.ts

@@ -17,8 +17,6 @@ import type {
 import { getLogger } from '../utils/getLogger.js'
 import { toStandardSchema } from '../utils/toStandardSchema.js'
 
-z.config(z.locales.en())
-
 /**
  * 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
@@ -27,7 +25,7 @@ z.config(z.locales.en())
  *
  * `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 `createLocalReq`.
+ * synthesized one built via `createPayloadRequest`.
  */
 export const buildMcpServer = ({
   authorizedMCP,
@@ -38,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 },

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

@@ -1,4 +1,4 @@
-import { createLocalReq, strictObject, z } from 'payload'
+import { createPayloadRequest, strictObject, z } from 'payload'
 
 import type { MCPToolResponse } from '../../../types.js'
 
@@ -53,7 +53,10 @@ export const authCollectionTool = defineCollectionTool({
     if (input.headers) {
       authHeaders = new Headers(input.headers)
     }
-    const authReq = await createLocalReq({ req: { headers: authHeaders } }, req.payload)
+    const authReq = await createPayloadRequest({
+      payload: req.payload,
+      req: { headers: authHeaders },
+    })
     const result = await req.payload.auth({ headers: authHeaders, req: authReq })
 
     if (result.user) {

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

@@ -1,16 +1,17 @@
 import {
   createDocumentsInputSchema,
   getCollectionVirtualFieldNames,
+  hasDraftValidationEnabled,
   stripVirtualFields,
   transformPointDataToPayload,
+  validateCollectionData,
 } from 'payload'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
-import { validateCollectionData } from '../validateEntityData.js'
+import { formatEntityError } from '../formatEntityError.js'
 import { fileInputSchema, resolveFile } from './fileInput.js'
-import { formatCollectionError } from './formatCollectionError.js'
 
 const DEFAULT_DESCRIPTION =
   'Create one or more documents. Each can have different data or a file. Prefer uploadReference after upload, externalURL for URLs, or base64 for small local files.'
@@ -29,43 +30,41 @@ export const createDocumentsTool = defineCollectionTool({
   input: createDocumentsInputSchema({ file: fileInputSchema }),
 }).handler(async ({ slug, authorizedMCP, input, req }) => {
   const payload = req.payload
+  const collectionConfig = payload.collections[slug]?.config
   const logger = getLogger({ payload })
-  const { depth, documents, draft, fallbackLocale, locale, populate, publishAllLocales, select } =
-    input
+  const {
+    depth,
+    documents,
+    draft,
+    fallbackLocale,
+    locale,
+    populate,
+    publishAllLocales,
+    returning,
+    select,
+  } = input
+  const shouldUsePartialSchema =
+    draft === true && collectionConfig !== undefined && !hasDraftValidationEnabled(collectionConfig)
 
   logger.info(`Creating ${documents.length} documents in collection: ${slug}`)
 
   try {
     const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, slug)
-    const docs: Array<{ doc: Record<string, unknown>; index: number }> = []
+    const docs: Array<
+      { doc: Record<string, unknown>; index: number } | { id: number | string; index: number }
+    > = []
     const errors: Array<{ index: number; message: string }> = []
     let validationSchema: Record<string, unknown> | undefined
 
     for (const [index, document] of documents.entries()) {
       try {
         const inputData = stripVirtualFields(document.data, virtualFieldNames)
-        const validationError = validateCollectionData({ slug, data: inputData, req })
-
-        if (validationError) {
-          const firstContent = validationError.content[0]
-          const validationContent = validationError.structuredContent as
-            | Record<string, unknown>
-            | undefined
-          const schema = validationContent?.schema
-
-          if (!validationSchema && schema && typeof schema === 'object') {
-            validationSchema = schema as Record<string, unknown>
-          }
-
-          errors.push({
-            index,
-            message:
-              firstContent?.type === 'text'
-                ? (firstContent.text.split('\n\nUse this schema')[0] ?? 'Invalid document data')
-                : 'Invalid document data',
-          })
-          continue
-        }
+        validateCollectionData({
+          slug,
+          data: inputData,
+          partial: shouldUsePartialSchema,
+          req,
+        })
 
         const parsedData = transformPointDataToPayload(inputData)
         const file = await resolveFile({ slug, input: document.file, req })
@@ -81,15 +80,37 @@ export const createDocumentsTool = defineCollectionTool({
           ...(file ? { file } : {}),
           ...(locale ? { locale } : {}),
           ...(fallbackLocale !== undefined ? { fallbackLocale } : {}),
-          ...(select ? { select } : {}),
+          select: returning ? select : { id: true },
         })
 
-        docs.push({ doc: result as Record<string, unknown>, index })
+        docs.push(
+          returning ? { doc: result as Record<string, unknown>, index } : { id: result.id, index },
+        )
       } catch (error) {
         const message = error instanceof Error ? error.message : 'Unknown error'
+        const formattedError = formatEntityError({
+          slug,
+          action: 'creating',
+          entity: 'collection',
+          error,
+          req,
+        })
+        const structuredContent = formattedError.structuredContent as
+          | { schema?: unknown }
+          | undefined
+        const schema = structuredContent?.schema
+        const errorContent = formattedError.content[0]
+        const formattedMessage =
+          errorContent?.type === 'text'
+            ? (errorContent.text.split('\n\nUse this schema')[0] ?? message)
+            : message
+
+        if (!validationSchema && schema && typeof schema === 'object') {
+          validationSchema = schema as Record<string, unknown>
+        }
 
         logger.error(`Error creating document at index ${index} in ${slug}: ${message}`)
-        errors.push({ index, message })
+        errors.push({ index, message: formattedMessage })
       }
     }
 
@@ -119,6 +140,6 @@ export const createDocumentsTool = defineCollectionTool({
     const message = error instanceof Error ? error.message : 'Unknown error'
 
     logger.error(`Error creating documents in ${slug}: ${message}`)
-    return formatCollectionError({ slug, action: 'creating', error, req })
+    return formatEntityError({ slug, action: 'creating', entity: 'collection', error, req })
   }
 })

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

@@ -1,4 +1,4 @@
-import { deleteDocumentsInputSchema } from 'payload'
+import { deleteDocumentsInputSchema, parseDocumentID } from 'payload'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
@@ -32,7 +32,7 @@ export const deleteDocumentsTool = defineCollectionTool({
   try {
     if (id !== undefined) {
       const result = await payload.delete({
-        id,
+        id: parseDocumentID({ id, collectionSlug: slug, payload }),
         collection: slug,
         depth,
         overrideAccess: authorizedMCP.overrideAccess,

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

@@ -1,14 +1,16 @@
 import {
   duplicateDocumentInputSchema,
   getCollectionVirtualFieldNames,
+  parseDocumentID,
   stripVirtualFields,
   transformPointDataToPayload,
+  validateCollectionData,
 } from 'payload'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
-import { formatCollectionError } from './formatCollectionError.js'
+import { formatEntityError } from '../formatEntityError.js'
 
 const DEFAULT_DESCRIPTION =
   'Duplicate a document in any collection by passing the collection slug and source document ID.'
@@ -36,10 +38,20 @@ export const duplicateDocumentTool = defineCollectionTool({
   try {
     const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, slug)
     const inputData = data ? stripVirtualFields(data, virtualFieldNames) : undefined
+
+    if (inputData) {
+      validateCollectionData({
+        slug,
+        data: inputData,
+        partial: true,
+        req,
+      })
+    }
+
     const parsedData = inputData ? transformPointDataToPayload(inputData) : undefined
 
     const result = await payload.duplicate({
-      id,
+      id: parseDocumentID({ id, collectionSlug: slug, payload }),
       collection: slug,
       depth,
       draft,
@@ -67,6 +79,6 @@ export const duplicateDocumentTool = defineCollectionTool({
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
     logger.error(`Error duplicating document in ${slug}: ${errorMessage}`)
-    return formatCollectionError({ slug, action: 'duplicating', error, req })
+    return formatEntityError({ slug, action: 'duplicating', entity: 'collection', error, req })
   }
 })

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

@@ -1,7 +1,11 @@
-import type { CollectionSlug, File, FileData, PayloadRequest } from 'payload'
+import type { CollectionSlug, File, PayloadRequest } from 'payload'
 
 import { APIError, z } from 'payload'
-import { getExternalFile, getFileFromUploadInstructions, isURLAllowed } from 'payload/internal'
+import {
+  externalURLInputSchema,
+  getFileFromUploadInstructions,
+  resolveURLUploadInput,
+} from 'payload/internal'
 import { sanitizeFilename } from 'payload/shared'
 
 const mimeTypeSchema = z
@@ -30,11 +34,7 @@ export const fileInputSchema = z
       mimeType: mimeTypeSchema.check(z.describe('The file MIME type, for example image/png.')),
       source: z.literal('base64'),
     }),
-    z.strictObject({
-      name: z.optional(z.string().check(z.minLength(1))).check(z.describe('File name override.')),
-      source: z.literal('externalURL'),
-      url: z.url().check(z.describe('The http or https URL to download.')),
-    }),
+    externalURLInputSchema,
     z.strictObject({
       file: uploadFileSchema.check(z.describe('getUploadInstructions file field post-upload.')),
       source: z.literal('uploadReference'),
@@ -75,6 +75,10 @@ export async function resolveFile({
     }
   }
 
+  if (input.source === 'externalURL') {
+    return resolveURLUploadInput({ slug, input, req })
+  }
+
   const uploadConfig = req.payload.collections[slug]?.config.upload
 
   if (!uploadConfig) {
@@ -82,48 +86,12 @@ export async function resolveFile({
   }
 
   const maxFileSize = req.payload.config.upload.limits?.fileSize
-  let file: File
-
-  if (input.source === 'base64') {
-    const data = decodeBase64({ maxFileSize, value: input.data })
-
-    file = {
-      name: sanitizeFilename(input.name),
-      data,
-      mimetype: input.mimeType,
-      size: data.length,
-    }
-  } else {
-    if (uploadConfig.pasteURL === false) {
-      throw new APIError(`Uploading files from URLs is disabled for collection "${slug}".`, 400)
-    }
-
-    const url = new URL(input.url)
-
-    if (!['http:', 'https:'].includes(url.protocol)) {
-      throw new APIError('File URLs must use http or https.', 400)
-    }
-
-    if (
-      typeof uploadConfig.pasteURL === 'object' &&
-      !isURLAllowed(input.url, uploadConfig.pasteURL.allowList)
-    ) {
-      throw new APIError('The provided file URL is not allowed.', 400)
-    }
-
-    file = await getExternalFile({
-      data: {
-        filename: sanitizeFilename(input.name || getURLFilename(url)),
-        url: input.url,
-      } as FileData,
-      req,
-      uploadConfig: {
-        ...uploadConfig,
-        externalFileHeaderFilter: uploadConfig.externalFileHeaderFilter ?? (() => ({})),
-      },
-    })
-    file.mimetype = file.mimetype?.split(';')[0] || 'application/octet-stream'
-    file.size = file.data.length
+  const data = decodeBase64({ maxFileSize, value: input.data })
+  const file: File = {
+    name: sanitizeFilename(input.name),
+    data,
+    mimetype: input.mimeType,
+    size: data.length,
   }
 
   if (maxFileSize !== undefined && Number.isFinite(maxFileSize) && file.size > maxFileSize) {
@@ -157,13 +125,3 @@ function decodeBase64({ maxFileSize, value }: { maxFileSize?: number; value: str
 
   return data
 }
-
-function getURLFilename(url: URL): string {
-  const pathSegment = url.pathname.split('/').pop() || 'upload'
-
-  try {
-    return decodeURIComponent(pathSegment)
-  } catch {
-    return pathSegment
-  }
-}

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

@@ -1,4 +1,4 @@
-import { findDocumentsInputSchema } from 'payload'
+import { findDocumentsInputSchema, parseDocumentID } from 'payload'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
@@ -45,10 +45,10 @@ export const findDocumentsTool = defineCollectionTool({
   )
 
   try {
-    if (id) {
+    if (id !== undefined) {
       try {
         const doc = await payload.findByID({
-          id,
+          id: parseDocumentID({ id, collectionSlug: slug, payload }),
           collection: slug,
           depth,
           overrideAccess: authorizedMCP.overrideAccess,

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

@@ -3,17 +3,18 @@ import type { Where } from 'payload'
 import {
   getCollectionInputSchema,
   getCollectionVirtualFieldNames,
+  parseDocumentID,
   stripVirtualFields,
   transformPointDataToPayload,
   updateDocumentInputSchema,
+  validateCollectionData,
 } from 'payload'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineCollectionTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
-import { validateCollectionData } from '../validateEntityData.js'
+import { formatEntityError } from '../formatEntityError.js'
 import { fileInputSchema, resolveFile } from './fileInput.js'
-import { formatCollectionError } from './formatCollectionError.js'
 
 const DEFAULT_DESCRIPTION =
   'Update documents. Prefer uploadReference after upload, externalURL for URLs, or base64 for small local files.'
@@ -46,6 +47,7 @@ export const updateDocumentTool = defineCollectionTool({
     overrideLock,
     populate,
     publishAllLocales,
+    returning,
     select,
     sort,
     trash,
@@ -60,17 +62,13 @@ export const updateDocumentTool = defineCollectionTool({
   try {
     const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, slug)
     const inputData = stripVirtualFields(data, virtualFieldNames)
-    const validationError = validateCollectionData({
+    validateCollectionData({
       slug,
       data: inputData,
       partial: true,
       req,
     })
 
-    if (validationError) {
-      return validationError
-    }
-
     const parsedData = transformPointDataToPayload(inputData)
     const file = await resolveFile({ slug, input: fileInput, req })
 
@@ -78,7 +76,7 @@ export const updateDocumentTool = defineCollectionTool({
 
     if (id !== undefined) {
       const result = await payload.update({
-        id,
+        id: parseDocumentID({ id, collectionSlug: slug, payload }),
         collection: slug,
         data: parsedData,
         depth,
@@ -90,20 +88,22 @@ export const updateDocumentTool = defineCollectionTool({
         populate,
         publishAllLocales,
         req,
-        select,
+        select: returning ? select : { id: true },
         trash,
         unpublishAllLocales,
         ...(file ? { file } : {}),
       })
 
+      const responseResult = returning ? result : { id: result.id }
+
       return {
         content: [
           {
             type: 'text',
-            text: `Document updated successfully in collection "${slug}"!\nUpdated document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
+            text: `Document updated successfully in collection "${slug}"!\nResult:\n\`\`\`json\n${JSON.stringify(responseResult)}\n\`\`\``,
           },
         ],
-        doc: result as Record<string, unknown>,
+        doc: responseResult as Record<string, unknown>,
       }
     }
 
@@ -120,7 +120,7 @@ export const updateDocumentTool = defineCollectionTool({
       populate,
       publishAllLocales,
       req,
-      select,
+      select: returning ? select : { id: true },
       sort,
       trash,
       unpublishAllLocales,
@@ -128,7 +128,7 @@ export const updateDocumentTool = defineCollectionTool({
       ...(file ? { file } : {}),
     })
 
-    const docs = result.docs || []
+    const docs = returning ? result.docs : result.docs.map(({ id }) => ({ id }))
     const errors = result.errors || []
 
     let responseText = `Multiple documents updated in collection "${slug}"!\nUpdated: ${docs.length} documents\nErrors: ${errors.length}\n---`
@@ -168,6 +168,6 @@ export const updateDocumentTool = defineCollectionTool({
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error'
     logger.error(`Error updating document in ${slug}: ${errorMessage}`)
-    return formatCollectionError({ slug, action: 'updating', error, req })
+    return formatEntityError({ slug, action: 'updating', entity: 'collection', error, req })
   }
 })

package/src/mcp/builtin/formatEntityError.ts

@@ -0,0 +1,77 @@
+import type { CollectionSlug, GlobalSlug, PayloadRequest } from 'payload'
+
+import { getCollectionInputSchema, getGlobalInputSchema, ValidationError } from 'payload'
+
+import type { MCPToolResponse } from '../../types.js'
+
+export const formatEntityError = ({
+  slug,
+  action,
+  entity,
+  error,
+  req,
+}:
+  | {
+      action: 'creating' | 'duplicating' | 'updating'
+      entity: 'collection'
+      error: unknown
+      req: PayloadRequest
+      slug: CollectionSlug
+    }
+  | {
+      action: 'updating'
+      entity: 'global'
+      error: unknown
+      req: PayloadRequest
+      slug: GlobalSlug
+    }): MCPToolResponse => {
+  const message = error instanceof Error ? error.message : 'Unknown error'
+  const target = entity === 'collection' ? `document in collection "${slug}"` : `global "${slug}"`
+
+  if (!isValidationError(error, message)) {
+    return {
+      content: [{ type: 'text', text: `Error ${action} ${target}: ${message}` }],
+      isError: true,
+    }
+  }
+
+  const schema =
+    entity === 'collection'
+      ? getCollectionInputSchema({ collectionSlug: slug, req })
+      : getGlobalInputSchema({ globalSlug: slug, req })
+  const errors = error instanceof ValidationError ? error.data.errors : [{ message }]
+  const validationMessage = errors
+    .map((issue) => `${'path' in issue ? `${issue.path}: ` : ''}${issue.message}`)
+    .join('\n')
+  const schemaText = schema
+    ? `\n\nUse this schema for data:\n\`\`\`json\n${JSON.stringify(schema)}\n\`\`\``
+    : ''
+
+  return {
+    content: [
+      { type: 'text', text: `Error ${action} ${target}: ${validationMessage}${schemaText}` },
+    ],
+    isError: true,
+    ...(schema
+      ? {
+          structuredContent: {
+            slug,
+            errors,
+            schema,
+          },
+        }
+      : {}),
+  }
+}
+
+const isValidationError = (error: unknown, message: string): boolean => {
+  if (error instanceof ValidationError) {
+    return true
+  }
+
+  const name = error && typeof error === 'object' && 'name' in error ? error.name : undefined
+
+  return (
+    name === 'CastError' || message.includes('Cast to ') || message.includes('validation failed')
+  )
+}

package/src/mcp/builtin/globals/updateTool.ts

@@ -3,12 +3,13 @@ import {
   stripVirtualFields,
   transformPointDataToPayload,
   updateGlobalInputSchema,
+  validateGlobalData,
 } from 'payload'
 
 import { defaultAccess } from '../../../defaultAccess.js'
 import { defineGlobalTool } from '../../../defineTool.js'
 import { getLogger } from '../../../utils/getLogger.js'
-import { validateGlobalData } from '../validateEntityData.js'
+import { formatEntityError } from '../formatEntityError.js'
 
 const DEFAULT_DESCRIPTION = 'Update any Payload global by passing the global slug and data.'
 
@@ -45,11 +46,7 @@ export const updateGlobalTool = defineGlobalTool({
   try {
     const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, slug)
     const inputData = stripVirtualFields(data, virtualFieldNames)
-    const validationError = validateGlobalData({ slug, data: inputData, req })
-
-    if (validationError) {
-      return validationError
-    }
+    validateGlobalData({ slug, data: inputData, req })
 
     const parsedData = transformPointDataToPayload(inputData)
 
@@ -88,10 +85,8 @@ export const updateGlobalTool = defineGlobalTool({
       doc: result as Record<string, unknown>,
     }
   } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-    logger.error(`Error updating global ${slug}: ${errorMessage}`)
-    return {
-      content: [{ type: 'text', text: `Error updating global "${slug}": ${errorMessage}` }],
-    }
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    logger.error(`Error updating global ${slug}: ${message}`)
+    return formatEntityError({ slug, action: 'updating', entity: 'global', error, req })
   }
 })