feat(plugin-mcp): ignore virtual fields in create and update operations (#15680)

Virtual fields (fields with `virtual: true`) are not stored and should
not be exposed as inputs or passed to Payload operations via MCP.

- Strips virtual fields from the MCP tool input schema so they don't
appear as accepted parameters
- Filters virtual fields them from parsed data before calling
`payload.create`, `payload.update`, and `payload.updateGlobal`.

Author: kendelljoseph

packages/plugin-mcp/src/mcp/getMcpHandler.ts

@@ -8,6 +8,11 @@ import type { MCPAccessSettings, PluginMCPServerConfig } from '../types.js'
 
 import { toCamelCase } from '../utils/camelCase.js'
 import { getEnabledSlugs } from '../utils/getEnabledSlugs.js'
+import {
+  getCollectionVirtualFieldNames,
+  getGlobalVirtualFieldNames,
+} from '../utils/getVirtualFieldNames.js'
+import { removeVirtualFieldsFromSchema } from '../utils/schemaConversion/removeVirtualFieldsFromSchema.js'
 import { registerTool } from './registerTool.js'
 
 // Tools
@@ -107,7 +112,16 @@ export const getMCPHandler = (
         // Collection Operation Tools
         enabledCollectionSlugs.forEach((enabledCollectionSlug) => {
           try {
-            const schema = configSchema.definitions?.[enabledCollectionSlug] as JSONSchema4
+            const rawSchema = configSchema.definitions?.[enabledCollectionSlug] as JSONSchema4
+
+            const virtualFieldNames = getCollectionVirtualFieldNames(
+              payload.config,
+              enabledCollectionSlug,
+            )
+            const schema = removeVirtualFieldsFromSchema(
+              JSON.parse(JSON.stringify(rawSchema)) as JSONSchema4,
+              virtualFieldNames,
+            )
 
             const toolCapabilities = mcpAccessSettings?.[
               `${toCamelCase(enabledCollectionSlug)}`
@@ -200,7 +214,13 @@ export const getMCPHandler = (
 
         enabledGlobalSlugs.forEach((enabledGlobalSlug) => {
           try {
-            const schema = configSchema.definitions?.[enabledGlobalSlug] as JSONSchema4
+            const rawSchema = configSchema.definitions?.[enabledGlobalSlug] as JSONSchema4
+
+            const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, enabledGlobalSlug)
+            const schema = removeVirtualFieldsFromSchema(
+              JSON.parse(JSON.stringify(rawSchema)) as JSONSchema4,
+              virtualFieldNames,
+            )
 
             const toolCapabilities = mcpAccessSettings?.[
               `${toCamelCase(enabledGlobalSlug)}`

packages/plugin-mcp/src/mcp/tools/global/update.ts

@@ -7,6 +7,10 @@ import { z } from 'zod'
 import type { PluginMCPServerConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
+import {
+  getGlobalVirtualFieldNames,
+  stripVirtualFields,
+} from '../../../utils/getVirtualFieldNames.js'
 import { convertCollectionSchemaToZod } from '../../../utils/schemaConversion/convertCollectionSchemaToZod.js'
 import { toolSchemas } from '../schemas.js'
 
@@ -45,6 +49,10 @@ export const updateGlobalTool = (
       let parsedData: Record<string, unknown>
       try {
         parsedData = JSON.parse(data)
+
+        const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, globalSlug)
+        parsedData = stripVirtualFields(parsedData, virtualFieldNames)
+
         if (verboseLogs) {
           payload.logger.info(
             `[payload-mcp] Parsed data for ${globalSlug}: ${JSON.stringify(parsedData)}`,

packages/plugin-mcp/src/mcp/tools/resource/create.ts

@@ -7,6 +7,10 @@ import { z } from 'zod'
 import type { PluginMCPServerConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
+import {
+  getCollectionVirtualFieldNames,
+  stripVirtualFields,
+} from '../../../utils/getVirtualFieldNames.js'
 import { convertCollectionSchemaToZod } from '../../../utils/schemaConversion/convertCollectionSchemaToZod.js'
 import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
 import { toolSchemas } from '../schemas.js'
@@ -49,6 +53,9 @@ export const createResourceTool = (
         // Transform point fields from object format to tuple array
         parsedData = transformPointDataToPayload(parsedData)
 
+        const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, collectionSlug)
+        parsedData = stripVirtualFields(parsedData, virtualFieldNames)
+
         if (verboseLogs) {
           payload.logger.info(
             `[payload-mcp] Parsed data for ${collectionSlug}: ${JSON.stringify(parsedData)}`,

packages/plugin-mcp/src/mcp/tools/resource/update.ts

@@ -7,6 +7,10 @@ import { z } from 'zod'
 import type { PluginMCPServerConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
+import {
+  getCollectionVirtualFieldNames,
+  stripVirtualFields,
+} from '../../../utils/getVirtualFieldNames.js'
 import { convertCollectionSchemaToZod } from '../../../utils/schemaConversion/convertCollectionSchemaToZod.js'
 import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
 import { toolSchemas } from '../schemas.js'
@@ -54,6 +58,9 @@ export const updateResourceTool = (
         // Transform point fields from object format to tuple array
         parsedData = transformPointDataToPayload(parsedData)
 
+        const virtualFieldNames = getCollectionVirtualFieldNames(payload.config, collectionSlug)
+        parsedData = stripVirtualFields(parsedData, virtualFieldNames)
+
         if (verboseLogs) {
           payload.logger.info(
             `[payload-mcp] Parsed data for ${collectionSlug}: ${JSON.stringify(parsedData)}`,

packages/plugin-mcp/src/utils/getVirtualFieldNames.ts

@@ -0,0 +1,53 @@
+import type { SanitizedConfig } from 'payload'
+
+import { fieldIsVirtual } from 'payload/shared'
+
+/**
+ * Returns the names of all top-level virtual fields for a given collection slug.
+ */
+export function getCollectionVirtualFieldNames(config: SanitizedConfig, slug: string): string[] {
+  const collection = config.collections.find((c) => c.slug === slug)
+
+  if (!collection) {
+    return []
+  }
+
+  return collection.flattenedFields
+    .filter((field) => 'name' in field && fieldIsVirtual(field))
+    .map((field) => (field as { name: string }).name)
+}
+
+/**
+ * Returns the names of all top-level virtual fields for a given global slug.
+ */
+export function getGlobalVirtualFieldNames(config: SanitizedConfig, slug: string): string[] {
+  const global = config.globals.find((g) => g.slug === slug)
+
+  if (!global) {
+    return []
+  }
+
+  return global.flattenedFields
+    .filter((field) => 'name' in field && fieldIsVirtual(field))
+    .map((field) => (field as { name: string }).name)
+}
+
+/**
+ * Strips virtual field values from a data object given a list of virtual field names.
+ */
+export function stripVirtualFields(
+  data: Record<string, unknown>,
+  virtualFieldNames: string[],
+): Record<string, unknown> {
+  if (virtualFieldNames.length === 0) {
+    return data
+  }
+
+  const stripped = { ...data }
+
+  for (const name of virtualFieldNames) {
+    delete stripped[name]
+  }
+
+  return stripped
+}

packages/plugin-mcp/src/utils/schemaConversion/removeVirtualFieldsFromSchema.ts

@@ -0,0 +1,27 @@
+import type { JSONSchema4 } from 'json-schema'
+
+/**
+ * Removes virtual fields from a JSON Schema by name so they don't appear
+ * in the generated MCP tool input schema.
+ */
+export function removeVirtualFieldsFromSchema(
+  schema: JSONSchema4,
+  virtualFieldNames: string[],
+): JSONSchema4 {
+  if (virtualFieldNames.length === 0) {
+    return schema
+  }
+
+  for (const name of virtualFieldNames) {
+    delete schema?.properties?.[name]
+  }
+
+  if (Array.isArray(schema.required)) {
+    schema.required = schema.required.filter((field) => !virtualFieldNames.includes(field))
+    if (schema.required.length === 0) {
+      delete schema.required
+    }
+  }
+
+  return schema
+}

packages/ui/src/elements/DocumentControls/index.tsx

@@ -285,11 +285,11 @@ export const DocumentControls: React.FC<{
                     {(unsavedDraftWithValidations ||
                       !autosaveEnabled ||
                       (autosaveEnabled && showSaveDraftButton)) && (
-                        <RenderCustomComponent
-                          CustomComponent={CustomSaveDraftButton}
-                          Fallback={<SaveDraftButton />}
-                        />
-                      )}
+                      <RenderCustomComponent
+                        CustomComponent={CustomSaveDraftButton}
+                        Fallback={<SaveDraftButton />}
+                      />
+                    )}
                     <RenderCustomComponent
                       CustomComponent={CustomPublishButton}
                       Fallback={<PublishButton />}

test/plugin-mcp/collections/Posts.ts

@@ -36,6 +36,14 @@ export const Posts: CollectionConfig = {
         description: 'Geographic location coordinates',
       },
     },
+    {
+      name: 'computedTitle',
+      type: 'text',
+      virtual: true,
+      admin: {
+        description: 'A virtual field that is computed and not stored in the database',
+      },
+    },
   ],
   hooks: {
     beforeRead: [

test/plugin-mcp/int.spec.ts

@@ -1470,6 +1470,131 @@ describe('@payloadcms/plugin-mcp', () => {
     })
   })
 
+  describe('Virtual Fields', () => {
+    it('should not include virtual fields in createPosts tool schema', async () => {
+      const apiKey = await getApiKey(true)
+      const response = await restClient.POST('/mcp', {
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          params: {},
+        }),
+        headers: {
+          Accept: 'application/json, text/event-stream',
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+      })
+
+      const json = await parseStreamResponse(response)
+
+      const createTool = json.result.tools.find((t: any) => t.name === 'createPosts')
+      expect(createTool).toBeDefined()
+      expect(createTool.inputSchema.properties.computedTitle).toBeUndefined()
+    })
+
+    it('should not include virtual fields in updatePosts tool schema', async () => {
+      const apiKey = await getApiKey(true)
+      const response = await restClient.POST('/mcp', {
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          params: {},
+        }),
+        headers: {
+          Accept: 'application/json, text/event-stream',
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+      })
+
+      const json = await parseStreamResponse(response)
+
+      const updateTool = json.result.tools.find((t: any) => t.name === 'updatePosts')
+      expect(updateTool).toBeDefined()
+      expect(updateTool.inputSchema.properties.computedTitle).toBeUndefined()
+    })
+
+    it('should ignore virtual fields when creating a post via MCP', async () => {
+      const apiKey = await getApiKey()
+      const response = await restClient.POST('/mcp', {
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: {
+            name: 'createPosts',
+            arguments: {
+              title: 'Virtual Field Create Test',
+              content: 'Testing virtual field exclusion on create',
+            },
+          },
+        }),
+        headers: {
+          Accept: 'application/json, text/event-stream',
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+      })
+
+      const json = await parseStreamResponse(response)
+
+      expect(json.result).toBeDefined()
+      expect(json.result.content[0].text).toContain(
+        'Resource created successfully in collection "posts"!',
+      )
+      expect(json.result.content[0].text).toContain('"title": "Virtual Field Create Test"')
+      expect(json.result.content[0].text).not.toContain('"computedTitle"')
+
+      // Clean up
+      const createdId = JSON.parse(
+        json.result.content[0].text.match(/```json\n([\s\S]*?)\n```/)?.[1] || '{}',
+      ).id
+      if (createdId) {
+        await payload.delete({ id: createdId, collection: 'posts' })
+      }
+    })
+
+    it('should ignore virtual fields when updating a post via MCP', async () => {
+      const post = await payload.create({
+        collection: 'posts',
+        data: { title: 'Virtual Field Update Test' },
+      })
+
+      const apiKey = await getApiKey(true, false)
+      const response = await restClient.POST('/mcp', {
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: {
+            name: 'updatePosts',
+            arguments: {
+              id: post.id,
+              title: 'Virtual Field Updated Title',
+            },
+          },
+        }),
+        headers: {
+          Accept: 'application/json, text/event-stream',
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+      })
+
+      const json = await parseStreamResponse(response)
+
+      expect(json.result).toBeDefined()
+      expect(json.result.content[0].text).toContain('Document updated successfully')
+      expect(json.result.content[0].text).toContain('"title": "Virtual Field Updated Title"')
+      expect(json.result.content[0].text).not.toContain('"computedTitle"')
+
+      await payload.delete({ id: post.id, collection: 'posts' })
+    })
+  })
+
   describe('payloadAPI context', () => {
     it('should call operations with the payloadAPI context as MCP', async () => {
       await payload.create({