MCP Plugin

  pnpm add @payloadcms/plugin-mcp

import { buildConfig } from 'payload'
import { mcpPlugin } from '@payloadcms/plugin-mcp'

const config = buildConfig({
  collections: [
    {
      slug: 'posts',
      fields: [],
    },
  ],
  plugins: [
    mcpPlugin({
      collections: {
        posts: {
          enabled: true,
        },
      },
    }),
  ],
})

export default config

mcpPlugin({
  collections: {
    posts: { enabled: true },
  },
  globals: {
    'site-settings': { enabled: { find: true, update: true } },
  },
})

curl -i 'http://localhost:3000/api/mcp' \
  -X POST \
  -H 'Authorization: Bearer MCP-USER-API-KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

{
  "mcp.servers": {
    "Payload": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:3000/api/mcp",
        "--header",
        "Authorization: Bearer MCP-USER-API-KEY"
      ]
    }
  }
}

{
  "mcpServers": {
    "Payload": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/api/mcp",
        "--header",
        "Authorization: Bearer MCP-USER-API-KEY"
      ]
    }
  }
}

claude mcp add --transport http Payload http://127.0.0.1:3000/api/mcp \
  --header "Authorization: Bearer MCP-USER-API-KEY"

{
  "mcpServers": {
    "Payload": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer MCP-USER-API-KEY"
      }
    }
  }
}

npx @modelcontextprotocol/inspector

curl -i 'http://localhost:3000/api/mcp' \
  -X POST \
  -H 'Authorization: Bearer MCP-USER-API-KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

mcpPlugin({
  globals: {
    'site-settings': {
      enabled: {
        find: true,
        update: true,
      },
      description:
        'Site-wide configuration settings including name, description, and maintenance mode.',
    },
  },
})

prompts: [
  {
    name: 'reviewContent',
    title: 'Content Review Prompt',
    description: 'Creates a prompt for reviewing content quality',
    argsSchema: {
      content: z.string().describe('The content to review'),
      criteria: z.array(z.string()).describe('Review criteria'),
    },
    handler: ({ content, criteria }, req) => ({
      messages: [
        {
          content: {
            type: 'text',
            text: `Please review this content based on the following criteria: ${criteria.join(', ')}\n\nContent: ${content}`,
          },
          role: 'user',
        },
      ],
    }),
  },
]

resources: [
  // Static resource
  {
    name: 'guidelines',
    title: 'Content Guidelines',
    description: 'Company content creation guidelines',
    uri: 'guidelines://company',
    mimeType: 'text/markdown',
    handler: (uri, req) => ({
      contents: [
        {
          uri: uri.href,
          text: '# Content Guidelines\n\n1. Keep it concise\n2. Use clear language',
        },
      ],
    }),
  },

  // Dynamic resource with template
  {
    name: 'userProfile',
    title: 'User Profile',
    description: 'Access user profile information',
    uri: new ResourceTemplate('users://profile/{userId}', { list: undefined }),
    mimeType: 'application/json',
    handler: async (uri, { userId }, req) => {
      // Fetch user data from your system
      const userData = await getUserById(userId)
      return {
        contents: [
          {
            uri: uri.href,
            text: JSON.stringify(userData, null, 2),
          },
        ],
      }
    },
  },
]

tools: [
  {
    name: 'getPostScores',
    description: 'Get useful scores about content in posts',
    handler: async (args, req) => {
      const { payload } = req
      const stats = await payload.find({
        collection: 'posts',
        where: {
          createdAt: {
            greater_than: args.since,
          },
        },
        req,
        overrideAccess: false,
        user: req.user,
      })

      return {
        content: [
          {
            type: 'text',
            text: `Found ${stats.totalDocs} posts created since ${args.since}`,
          },
        ],
      }
    },
    parameters: z.object({
      since: z.string().describe('ISO date string for filtering posts'),
    }).shape,
  },
]

// In a tool call, pass select as a JSON string:
// arguments: { select: '{"title": true, "slug": true}' }

curl -i 'http://localhost:3000/api/mcp' \
  -X POST \
  -H 'Authorization: Bearer MCP-USER-API-KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "findPosts",
      "arguments": {
        "select": "{\"title\": true, \"slug\": true}"
      }
    }
  }'

mcpPlugin({
  collections: {
    posts: {
      enabled: true,
      overrideResponse: (response, doc, req) => {
        req.payload.logger.info('[MCP] Post response intercepted')

        // Append additional context
        response.content.push({
          type: 'text',
          text: `Document last modified by: ${doc.updatedBy ?? 'unknown'}`,
        })

        return response
      },
    },
    users: {
      enabled: { find: true },
      overrideResponse: (response, doc, req) => {
        // Redact sensitive fields before the model sees the document
        response.content = response.content.map((item) => ({
          ...item,
          text: item.text
            .replace(/"hash":\s*"[^"]*"/g, '"hash": "[redacted]"')
            .replace(/"salt":\s*"[^"]*"/g, '"salt": "[redacted]"'),
        }))
        return response
      },
    },
  },
})

mcpPlugin({
  overrideApiKeyCollection: (collection) => {
    // Add fields to the API Keys collection
    collection.fields.push({
      name: 'department',
      type: 'select',
      options: [
        { label: 'Development', value: 'dev' },
        { label: 'Marketing', value: 'marketing' },
      ],
    })

    // You can also add hooks
    collection.hooks?.beforeRead?.push(({ doc, req }) => {
      req.payload.logger.info('Before Read MCP hook!')
      return doc
    })
    return collection
  },
  // ... other options
})

import { type MCPAccessSettings, mcpPlugin } from '@payloadcms/plugin-mcp'

// ... other config

mcpPlugin({
  overrideAuth: (req, getDefaultMcpAccessSettings) => {
    const { payload } = req

    // This will return the default MCPAccessSettings
    // getDefaultMcpAccessSettings()

    payload.logger.info('Custom access Settings for all MCP traffic')
    return {
      posts: {
        find: true,
      },
      products: {
        find: true,
      },
    } as MCPAccessSettings
  },
  // ... other options
})

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
      },
    ],
  },
}

curl -i 'http://localhost:3000/api/mcp' \
  -X POST \
  -H 'Authorization: Bearer MCP-USER-API-KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "findPosts",
      "arguments": {
        "locale": "es",
        "fallbackLocale": "en"
      }
    }
  }'

mcpPlugin({
  mcp: {
    handlerOptions: {
      onEvent: (event) => {
        // Forward to your analytics pipeline, audit log, etc.
        console.log('[MCP event]', event)
      },
    },
  },
})

// Weak — a model has no idea what kind of posts these are or when to use this collection
mcpPlugin({
  collections: {
    posts: {
      enabled: true,
      description: 'My posts',
    },
  },
})

// Strong — the model understands the content and its purpose
mcpPlugin({
  collections: {
    posts: {
      enabled: true,
      description:
        'Published articles covering science and nature topics, with title, body, tags, and publication date.',
    },
  },
})

# Return only title and slug instead of the full document
-d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"findPosts","arguments":{"select":"{\"title\": true, \"slug\": true}"}}}'

mcpPlugin({
  collections: {
    posts: {
      enabled: { find: true }, // create / update / delete are off
    },
  },
})