feat(plugin-mcp): adds MCP context to req.payloadAPI (#14595)

- Adds `MCP` option to `req.payloadAPI`

Users can write a conditional to detect when the Payload API context is
'MCP' related.

```ts
import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    {
      name: 'title',
      type: 'text',
      admin: {
        description: 'The title of the post',
      },
      required: true,
    },

    // ... other fields
  ],
  hooks: {
    beforeRead: [
      ({ doc, req }) => {
        if (req.payloadAPI === 'MCP') {
          doc.title = `${doc.title} (MCP Hook Override)`
        }
        return doc
      },
    ],
  },
}

Author: kendelljoseph

packages/payload/src/types/index.ts

@@ -114,10 +114,12 @@ type PayloadRequestData = {
     tempFilePath?: string
   }
 }
-export type PayloadRequest = CustomPayloadRequestProperties &
-  Partial<Request> &
-  PayloadRequestData &
-  Required<Pick<Request, 'headers'>>
+export interface PayloadRequest
+  extends CustomPayloadRequestProperties,
+    Partial<Request>,
+    PayloadRequestData {
+  headers: Request['headers']
+}
 
 export type { Operator }
 

packages/payload/src/utilities/createLocalReq.ts

@@ -123,7 +123,6 @@ export const createLocalReq: CreateLocalReq = async (
     (await getLocalI18n({ config: payload.config, language: payload.config.i18n.fallbackLanguage }))
 
   if (!req.headers) {
-    // @ts-expect-error eslint-disable-next-line no-param-reassign
     req.headers = new Headers()
   }
 

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

@@ -13,6 +13,8 @@ export const initializeMCPHandler = (pluginOptions: PluginMCPServerConfig) => {
     const MCPHandlerOptions = MCPOptions.handlerOptions || {}
     const useVerboseLogs = MCPHandlerOptions.verboseLogs ?? false
 
+    req.payloadAPI = 'MCP' as const
+
     const getDefaultMcpAccessSettings = async (overrideApiKey?: null | string) => {
       const apiKey =
         (overrideApiKey ?? req.headers.get('Authorization')?.startsWith('Bearer '))

packages/plugin-mcp/src/index.ts

@@ -5,6 +5,12 @@ import type { MCPAccessSettings, PluginMCPServerConfig } from './types.js'
 import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
 import { initializeMCPHandler } from './endpoints/mcp.js'
 
+declare module 'payload' {
+  export interface PayloadRequest {
+    payloadAPI: 'GraphQL' | 'local' | 'MCP' | 'REST'
+  }
+}
+
 export type { MCPAccessSettings }
 /**
  * The MCP Plugin for Payload. This plugin allows you to add MCP capabilities to your Payload project.

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

@@ -50,6 +50,7 @@ export const createResourceTool = (
       // Create the resource
       const result = await payload.create({
         collection: collectionSlug,
+        req,
         // 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,

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

@@ -78,6 +78,7 @@ export const deleteResourceTool = (
         collection: collectionSlug,
         depth,
         overrideAccess: false,
+        req,
         user,
       }
 

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

@@ -65,6 +65,7 @@ export const findResourceTool = (
             id,
             collection: collectionSlug,
             overrideAccess: false,
+            req,
             user,
           })
 
@@ -117,6 +118,7 @@ ${JSON.stringify(doc, null, 2)}`,
         limit,
         overrideAccess: false,
         page,
+        req,
         user,
       }
 

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

@@ -116,6 +116,7 @@ export const updateResourceTool = (
           draft,
           overrideAccess: false,
           overrideLock,
+          req,
           user,
           ...(filePath && { filePath }),
           ...(overwriteExistingFiles && { overwriteExistingFiles }),
@@ -162,6 +163,7 @@ ${JSON.stringify(result, null, 2)}
           draft,
           overrideAccess: false,
           overrideLock,
+          req,
           user,
           where: whereClause,
           ...(filePath && { filePath }),

test/plugin-mcp/collections/Posts.ts

@@ -28,4 +28,14 @@ export const Posts: CollectionConfig = {
       },
     },
   ],
+  hooks: {
+    beforeRead: [
+      ({ doc, req }) => {
+        if (req.payloadAPI === 'MCP') {
+          doc.title = `${doc.title} (MCP Hook Override)`
+        }
+        return doc
+      },
+    ],
+  },
 }

test/plugin-mcp/int.spec.ts

@@ -401,8 +401,50 @@ describe('@payloadcms/plugin-mcp', () => {
     expect(json.result.content[0].text).toContain('Total: 1 documents')
     expect(json.result.content[0].text).toContain('Page: 1 of 1')
     expect(json.result.content[0].text).toContain('```json')
-    expect(json.result.content[0].text).toContain('"title": "Test Post for Finding"')
+    expect(json.result.content[0].text).toContain('"content": "Content for test post."')
     expect(json.result.content[1].type).toBe('text')
     expect(json.result.content[1].text).toContain('Override MCP response for Posts!')
   })
+
+  it('should call operations with the payloadAPI context as MCP', async () => {
+    await payload.create({
+      collection: 'posts',
+      data: {
+        title: 'Test Post for Finding',
+        content: 'Content for test post.',
+      },
+    })
+
+    const apiKey = await getApiKey()
+    const response = await restClient.POST('/mcp', {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json, text/event-stream',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: {
+          name: 'findPosts',
+          arguments: {
+            limit: 1,
+            page: 1,
+            where: '{"title": {"contains": "Test Post for Finding"}}',
+          },
+        },
+      }),
+    })
+
+    const json = await parseStreamResponse(response)
+
+    expect(json).toBeDefined()
+    expect(json.result).toBeDefined()
+    expect(json.result.content).toHaveLength(2)
+    expect(json.result.content[0].type).toBe('text')
+    expect(json.result.content[0].text).toContain(
+      '"title": "Test Post for Finding (MCP Hook Override)"',
+    )
+  })
 })