MCP Plugin

https://www.npmjs.com/package/@payloadcms/plugin-mcp

This plugin adds Model Context Protocol capabilities.

Core features

Adds a collection to your config where:
You can allow / disallow find, create, update, and delete operations for each collection
You can to allow / disallow capabilities in real time
You can define your own Prompts, Tools and Resources available over MCP

Installation

Install the plugin using any JavaScript package manager like pnpm, npm, or Yarn:

1pnpm add @payloadcms/plugin-mcp

Basic Usage

In the plugins array of your Payload Config, call the plugin with options:

1import { buildConfig } from 'payload'
2import { mcpPlugin } from '@payloadcms/plugin-mcp'
3
4const config = buildConfig({
5  collections: [
6    {
7      slug: 'posts',
8      fields: [],
9    },
10  ],
11  plugins: [
12    mcpPlugin({
13      collections: {
14        posts: {
15          enabled: true,
16        },
17      },
18    }),
19  ],
20})
21
22export default config

Options

Option	Type	Description
`collections`	`object`	An object of collection slugs to use for MCP capabilities.
`collections[slug]`	`object`	An object of collection slugs to use for MCP capabilities.
`collections[slug].description`	`string`	A description for the collection.
`collections[slug].override`	`function`	A function that allows you to override the data generated by the LLM before it is used in an operation.
`collections[slug].overrideResponse`	`function`	A function that allows you to override the response from the operation tool call
`collections[slug].enabled`	`object or boolean`	Determines whether the LLM can find, create, update, and delete documents in the collection.
`collections[slug].enabled.find`	`boolean`	Whether to allow the LLM to find documents in the collection.
`collections[slug].enabled.create`	`boolean`	Whether to allow the LLM to create documents in the collection.
`collections[slug].enabled.update`	`boolean`	Whether to allow the LLM to update documents in the collection.
`collections[slug].enabled.delete`	`boolean`	Whether to allow the LLM to delete documents in the collection.
`disabled`	`boolean`	Disable the MCP plugin while keeping database schema consistent.
`overrideApiKeyCollection`	`function`	A function that allows you to override the automatically generated API Keys collection.
`mcp`	`object`	MCP options that allow you to customize the MCP server.
`mcp.tools`	`array`	An array of custom tools to add to the MCP server.
`mcp.tools.name`	`string`	The name of the tool.
`mcp.tools.description`	`string`	The description of the tool.
`mcp.tools.handler`	`function`	The handler function for the tool.
`mcp.tools.parameters`	`object`	The parameters for the tool (Zod schema).
`mcp.prompts`	`array`	An array of custom prompts to add to the MCP server.
`mcp.prompts.name`	`string`	The name of the prompt.
`mcp.prompts.title`	`string`	The title of the prompt (used by LLMs to determine when to use it).
`mcp.prompts.description`	`string`	The description of the prompt.
`mcp.prompts.handler`	`function`	The handler function for the prompt.
`mcp.prompts.argsSchema`	`object`	The arguments schema for the prompt (Zod schema).
`mcp.resources`	`array`	An array of custom resources to add to the MCP server.
`mcp.resources.name`	`string`	The name of the resource.
`mcp.resources.title`	`string`	The title of the resource (used by LLMs to determine when to use it).
`mcp.resources.description`	`string`	The description of the resource.
`mcp.resources.handler`	`function`	The handler function for the resource.
`mcp.resources.uri`	`string or object`	The URI of the resource (can be a string or ResourceTemplate for dynamic URIs).
`mcp.resources.mimeType`	`string`	The MIME type of the resource.
`mcp.handlerOptions`	`object`	The handler options for the MCP server.
`mcp.handlerOptions.basePath`	`string`	The base path for the MCP server (default: '/api').
`mcp.handlerOptions.verboseLogs`	`boolean`	Whether to log verbose logs to the console (default: false).
`mcp.handlerOptions.maxDuration`	`number`	The maximum duration for the MCP server requests (default: 60).
`mcp.serverOptions`	`object`	The server options for the MCP server.
`mcp.serverOptions.serverInfo`	`object`	The server info for the MCP server.
`mcp.serverOptions.serverInfo.name`	`string`	The name of the MCP server (default: 'Payload MCP Server').
`mcp.serverOptions.serverInfo.version`	`string`	The version of the MCP server (default: '1.0.0').

Override API Keys Collection

The plugin automatically creates an API Keys collection that provides high-resolution control over MCP capabilities. This collection allows admins to:

Create API keys for MCP clients
Allow or disallow specific MCP capabilities in real-time
Control which collections can be accessed via MCP
Enable or disable custom tools

You can customize this collection using the overrideApiKeyCollection option:

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

Custom Prompts

Prompts allow LLMs to generate structured messages for specific tasks. Each prompt defines a schema for arguments and returns formatted messages:

1prompts: [
{
  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 }) => ({
    messages: [
      {
        content: {
          type: 'text',
          text: `Please review this content based on the following criteria: ${criteria.join(', ')}\n\nContent: ${content}`,
        },
        role: 'user',
      },
    ],
  }),
},
22]

Custom Resources

Resources provide access to data or content that LLMs can read. They can be static or dynamic with parameterized URIs:

1resources: [
// Static resource
{
  name: 'guidelines',
  title: 'Content Guidelines',
  description: 'Company content creation guidelines',
  uri: 'guidelines://company',
  mimeType: 'text/markdown',
  handler: (uri) => ({
    contents: [
      {
        uri: uri.href,
        text: '# Content Guidelines\n\n1. Keep it concise\n2. Use clear language',
      },
    ],
  }),
},
18
// 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 }) => {
    // Fetch user data from your system
    const userData = await getUserById(userId)
    return {
      contents: [
        {
          uri: uri.href,
          text: JSON.stringify(userData, null, 2),
        },
      ],
    }
  },
},
39]

Data Override Example

Use override functions to modify data before it's processed:

1collections: {
posts: {
  enabled: true,
  override: (original, req) => {
    // Log the operation
    req.payload.logger.info('MCP operation on posts:', original)
7
    // Sanitize or validate data
    const sanitized = {
      ...original,
      title: sanitizeTitle(original.title),
      publishedAt: original.publishedAt || new Date().toISOString(),
    }
14
    return sanitized
  },
},
18}

Use overrideResponse to modify response data:

1collections: {
posts: {
  enabled: true,
  overrideResponse: (response, doc, req) => {
    response.content.push({
      type: 'text',
      text: 'Additional response for Posts!',
    })
    return response
  },
},
12}

Custom Tool with Database Access

Custom tools allow you to extend MCP capabilities beyond basic CRUD operations. Use them when you need to perform complex queries, aggregations, or business logic that isn't covered by the standard collection operations.

1tools: [
{
  name: 'getPostStats',
  description: 'Get statistics about posts in the system',
  handler: async (args, { payload }) => {
    const stats = await payload.find({
      collection: 'posts',
      where: {
        createdAt: {
          greater_than: args.since,
        },
      },
    })
14
    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,
},
28]

Performance

The description you choose to use for your collection greatly impacts the way a model will decide to use it.

The description in this example is more difficult for a model to understand it's purpose.

1// Weak
2const config = buildConfig({
// ...
plugins: [
  mcpPlugin({
    collections: {
      posts: {
        enabled: true,
        description: 'My posts',
      },
    },
  }),
],
14})

The description in this example gives a model a stronger ability to know when to use this collection.

1// Strong
2const config = buildConfig({
// ...
plugins: [
  mcpPlugin({
    collections: {
      posts: {
        enabled: true,
        description: 'My posts',
      },
    },
  }),
],
14})

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.