[RFC] MCP Plugin

[kendelljoseph]

Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you’re building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
source - modelcontextprotocol.io

📝 Plugin Documentation

Background

This plugin adds MCP server capabilities to Payload. By using this plugin, Payload can be used as a Connector by MCP clients to interact with the data in your collections. It can also return prompts to use in a model's context, and run functions defined as Tools. You can also create your own Resources to further extend the capabilities of your server.

⭐ Yes, this means chat agents can reference data in your collections, use your prompts to guide their responses, and run custom functions to perform actions you define. This plugin gives models the ability to access content, however you can manage access to that content in real-time using the API or the Admin panel.

How does it work?

Collections

You control which collections can be modified by MCP clients and create custom Tools, Prompts and Resources.

In this example, the "Posts" collection is enabled. A model will be able to perform find, create, update, and delete operations on the posts collection.

mcpPlugin({
  collections: {
    posts: {
      enabled: true,
    },
  },
}
// 🚨 Collections will still use existing `hooks`, `access controls`, etc. that are already defined on those collections.

You can restrict operations a model can perform on a collection. Here is an example of a config that only allows find and create operations on the "Posts" collection.

mcpPlugin({
  collections: {
    posts: {
      enabled: {
        find: true,
        create: true,
      }
    },
  },
}
// 🚨 If you use this format the default value for undefined operations is `false`

You can add a description to help a model understand your collection.

mcpPlugin({
  collections: {
    posts: {
      enabled: true,
    },
    description: 'The Posts collection contains the posts for the blog about the latest news and events.',
  },
}
// 🚨 The quality of descriptions will greatly impact the quality of model responses!

Tools

These are the Payload tools that LLMs use to interact with collection documents.

Resources

Tool	Description
findResources	Find documents in a collection
createResource	Create a new document
updateResource	Update documents by ID or where clause
deleteResource	Delete documents by ID or where clause

You can create your own Tools to extend the capabilities of your server.

Here is an example of a basic tool that rolls a virtual dice with a specified number of sides.

tools: [
  {
    name: 'diceRoll',
    description: 'Rolls a virtual dice with a specified number of sides',
    handler: (args: Record<string, unknown>) => {
      const sides = (args.sides as number) || 6
      const result = Math.floor(Math.random() * sides) + 1
      return Promise.resolve({
        content: [
          {
            type: 'text' as const,
            text: `# Dice Roll Result\n\n**Sides:** ${sides}\n**Result:** ${result}\n\n🎲 You rolled a **${result}** on a ${sides}-sided die!`,
          },
        ],
      })
    },
    parameters: z.object({
      sides: z
        .number()
        .int()
        .min(2)
        .max(1000)
        .optional()
        .default(6)
        .describe('Number of sides on the dice (default: 6)'),
    }).shape,
  },
]

Prompts

You can also create your own Prompts to extend the capabilities of your server.

Here is an example of a basic reusable prompt that echoes a message.

prompts: [
  {
    name: 'echo',
    argsSchema: { message: z.string() },
    description: 'Creates a prompt to process a message',
    title: 'Echo Prompt',
    handler: ({ message }: { message: string }) => ({
      messages: [
        {
          content: {
            type: 'text',
            text: `Please process this message: ${message}`,
          },
          role: 'user',
        },
      ],
    }),
  },
],

Resources

You can also create your own Resources to extend the capabilities of your server.

Here is an example of a basic resource that contains static data.

resources: [
  // Resource with a static URI
  {
    name: 'data',
    description: 'Data is a resource that contains special data.',
    handler: (uri) => ({
      contents: [
        {
          uri: uri.href,
          text: 'My special data.',
        },
      ],
    }),
    mimeType: 'text/plain',
    title: 'Data',
    uri: 'data://app',
  },
]

Security

Using the Admin or the API you create API Keys that control MCP access to resources. MCP Clients must must include the API Key in the request headers when making MCP requests. If the API Key is not included, the request will be rejected.

Example MCP Client request to list tools:

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

🚨 Collections must be allowed by Admins or the API to be accessible by MCP clients.

🚨 Tools, prompts, and resources are initially allowed.

IMPORTANT: Enabling a collection in your config does not mean it is immedately accessable! You have to allow the capability as well. You can do this via the Admin panel or the API by modifying the document in the payload-mcp-api-keys collection.

Capabilities

We are currently implementing these capabilities from the MCP specification.

• Prompts
• Resources
• Tools
• Roots
• Sampling
• Elicitation
• Completion
• Logging
• Pagination

Transports

The protocol currently defines two standard transport mechanisms for client-server communication:
source - modelcontextprotocol.io

1. STDIO
2. Streamable HTTP

Currently Implemented Transports in Payload MCP Plugin:

• Streamable HTTP
• STDIO

Basic Usage

In the plugins array of your Payload Config

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

Connectors

Connectors are MCP clients that can use MCP servers like Payload with the plugin installed.

Visual Studio Code

{
  "mcp.servers": {
    "Payload": {
      "url": "http://127.0.0.1:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer API-KEY-HERE"
      }
    }
  }
}

Cursor

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

Claude Code

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

Testing your MCP endpoint

I highly recommend using npx @modelcontextprotocol/inspector to test your MCP server.
Your default MCP endpoint is: http://127.0.0.1:3000/api/mcp

npx @modelcontextprotocol/inspector

Open Questions

• How are you thinking about MCP?
• How will you use MCP?

[the-e-arc]

We have a client who is using PayloadCMS for educational institute, i.e for school & college.
so we are planning to add Chat with data, i.e the top educational institute management can ask the AI -> How many students haven’t paid their fees for this month yet?

I'm guessing this is exactly what we are building, right?

[the-e-arc]

Can't believe the perfect timing of this! Kudos to the whole team!

I already gave this a shot, it seemed to work but I have a few doubts and a few bugs to report,

1. I assumed the collection access (i.e read access) will be enforced. I'm using this in a multi-tenant environment and each user has limited access, for eg - a tenant admin only has access to their tenant but with MCP all tenant data was returned.
2. The logger didn't seemed to work 😅
3. I also wanna know what all context is sent to the AI during tool call.

Thanks once again for this!

[kendelljoseph]

1. We'll have to make a full pass at multi-tenant security. At the moment the API key is bound to a specific user, however may not be honoring multi-tenant setups. -- We do have some updates to this in the works, but I will include this update in that effort.

2. Darn :)

3. The context sent during the tool call is the full document found, see here. In production, folks will likely want to trim that down to only return the parts of the document you want to truly share using overrideResponse.

Sanitizing your responses is crucial for security!

We might even make it the default response, and to get the full doc you'll have to set something like returnOriginalDoc = true. (Still a work in progress here)

We will emphasize this more in the docs before we fully release this plugin.

You are most welcome!

[kendelljoseph]

@the-e-arc

2. Did you check the console? Or were you expecting logging somewhere in a collection?

For example should enabling logging also keep a log of Prompts, Tool Calls, etc in a way you can see them them in the admin in a collection?

The latter is what I was thinking would be nice to have to increase traceability.

[the-e-arc]

I checked the console and i was only seeing the 200 /api/mcp logging not the console.log/print statements; and yes, the latter would be good to have!

[kendelljoseph]

We fixed the multi-tenant issue. Access controls are now properly honored using the user associated with the API Key.

[anhdd-kuro]

Hi! Thanks for the great implementation!
Can you please provide an example setting for the custom prompt?
Here is my current setting, copied from the doc, but it seems like nothing happens.
For example: I want to add follow up "Summary the post" after find. How can I archive that

mcpPlugin({
      mcp: {
        prompts: [
          {
            name: 'summaryContent',
            title: 'Content Summary Prompt',
            description: 'Creates a prompt for summarize content',
            argsSchema: {
              content: z.string().describe('The content to review'),
            },
            handler: ({ content }) => {
              console.log('Custom prompt run')

              return {
                messages: [
                  {
                    content: {
                      type: 'text',
                      text: `Please summarize the following content.: ${content}`,
                    },
                    role: 'user',
                  },
                ],
              }
            },
          },
        ],
      },
      collections: {
        posts: {
          enabled: {
            find: true,
            create: false,
            update: false,
            delete: false,
          },
          description:
            'Announcement article collection. Can be used to search articles containing information such as title, content, publication date and time, category, and more.',
        },
      },
    }),

And what version of zod it' supporting ? I keep getting this type error ( Using zod v4 )
Type 'ZodString' is missing the following properties from type 'ZodType<any, any, any>': _type, _parse, _getType, _getOrReturnCtx, and 7 more.ts(2740)

[kendelljoseph]

@anhdd-kuro

Use Zod 3 -- not Zod 4

Zod 3 is required. We're using the MCP Typescript SDK, which is at version 3 right now, even though version 4 is available.
Source

If you need Zod 4, then you will have to install Zod 3, and use an alias. Sorry about that, the MCP folks are currently working on updating to Zod 4.

~

Tool vs Prompt

Models can ask your MCP server for a prompt to use like the one you have there. That is not the same as a tool call.

Although it might be tempting to add functional logic to a prompt call to make it behave like a tool call, that gets messy very quickly.

The data you are returning is context that helps the model respond. So in your handler you could also return text content that says what to do with the content returned, and the model will try to honor that.

Here is an example of a tool that would return a list of documents to draft release notes. If you wanted to modify this example to create a post summarizer tool you could.

import { buildConfig } from 'payload'
import { z } from 'zod' // Alias to your version of Zod 3 (if you are already using Zod 4)
import { mcpPlugin } from '@payloadcms/plugin-mcp'

export default buildConfig({
  collections: [{ slug: 'posts', fields: [] }],
  plugins: [mcpPlugin({
    collections: {
      posts: {
        enabled: { find: true },
        description: 'Published articles with titles, tags, and createdAt timestamps',
      },
    },
    mcp: {
      tools: [{
        name: 'draftReleaseNotes',
        description: 'Summarize the latest posts into bullet points',
        parameters: z.object({ limit: z.number().int().positive().default(5) }).shape,
        handler: async ({ limit }, { payload }) => {
          const { docs } = await payload.find({ collection: 'posts', limit, sort: '-createdAt', depth: 0 })
          return { content: [{ type: 'text', text: docs.map(d => `- ${d.title}`).join('\n') || 'No posts yet.' }] }
        },
      }],
    },
  })],
})

Example data returned to the model:

- Cats and Dogs, what's the deal?
- Lions, Tigers, Bears, oh my!
- 10 questions you should ask your friends

The model will then use that data returned from that tool call to generate a response.

[kendelljoseph]

Can you please provide an example setting for the custom prompt?

To be clear here. This plugin does not give you the ability to inference on a model. This is for Software with "MCP Clients" to be able to connect and perform actions on your Payload application.

handler: ({ content }) => {
  console.log('Custom prompt run') // Use your own model inferencing library here

  return {
    messages: [
      {
        content: {
          type: 'text',
          text: `Please summarize the following content.: ${content}`,
        },
        role: 'user',
      },
    ],
  }
},

The Prompts on your MCP server are for when an MCP client thinks "I need to find a prompt to use to answer this question, let me check what is available." -- Then it can check your MCP server for the a prompt to use, which could include some dynamic retrieval or inference on your server.

MCP is not a way to use a model -- it is a way for models to communicate.

Make sense?

[rob-at-cortex]

this is great. is there any plan to add oauth so we can avoid static API Keys?
should be a case of accepting the Bearer token, validate and extract the user. compare that against the users collection.
or can we overload this functionality somewhere ?

[the-e-arc]

this would solve the multi-tenant security issue as well

[kendelljoseph]

@the-e-arc This PR should solve the multi-tenant issue.

[kendelljoseph]

This PR allows custom auth functions.
#14538

[the-e-arc]

wow, multi-tenant issue is resolved! any eta?

[kendelljoseph]

Yep, it's deployed in 3.64.0

[LeonGatt]

Awesome stuff! 🎉 Also Strapi’s official MCP extension is just around the corner too. Super excited to play with this one!
BTW are u planning to enable working with jobs and queue?
Thanks!

[kendelljoseph]

Thanks!

There is an experimental jobs tool that you can play with, along with some others. There are some amazing things that can be done for sure!

⚠️ Experimental tools do not work in production environments and may be removed at any time.

[nick-vogel]

Adding a few of my thoughts from the Discord to this so they don't get lost. Also, a few notes from when I was messing with it again yesterday.

1. Adding the MCP to an AI agent was confusing at first. Adding the common ones (listed here in the RFC) to the docs would be helpful. I know those will be added in the future when it's not in beta, so just a link to the section here in the RFC would've been helpful.
2. The copy icon in the API key collection should have some kind of interaction to provide user feedback.
3. I didn't test updating partial and nested data again yesterday. When I first tried to update a page from the website template, my AI agent couldn't do it because it needed to pass in all the data again instead of just the title, for example. Creating pages with blocks didn't work either.
4. More information about the need to enable the default tools in the admin UI in the docs would be helpful. It's not clear that you need to enable the collection and then go into the API key collection to enable the tools.
5. More information about how resources work. A real world example would be helpful since the section in the RFC uses a dummy application.
6. More information about the serverOptions.serverInfo would be helpful. Where does the name and version show up? When adding the mcp server to Claude Code, it takes the initial name from the CLI command from above.

Overall, I really like this new plugin and think it will make using AI to develop with Payload much easier.

[kendelljoseph]

Thank you for the feedback!

1. Heard -- docs will be updated soon!
2. A custom api-key component might be possible with the slots we have, I'll find out.
3. We can definitely improve complex nesting behaviors! Blocks and visual components we're buggy before, I'm not surprised to hear this -- we'll dig into it.
4. The enable/allow interaction can be more clear. The purpose of this capability is to prevent MCP resource interactions at startup without first being toggled. This way you can enable a collection as resource within your application, and allow traffic to flow in a different step. We can start by explaining this purpose better in the docs.
5. resources are described in the protocol as:

Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a URI.

The example from the protocol references a file that can be streamed and looks looks like:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ]
  }
}

This is different from a tool because it defines an expected way that data will flow across as a mimeType. The combination of being able to define a uri, and also the type of binary data traffic is different from when you define a tool where file types and streams don't matter.

This is important for content providers that stream data, like llms or media.

We can include something like this in the docs.

6. The initialize MCP response looks like:

{
  "capabilities": { },
  "serverInfo": {
    "name": "My Custom MCP Server",
    "version": "1.0.0"
  }
}

the serverInfo config is what changes the information in this response. MCP clients may sometimes choose to display this information over the label in the mcp.json you may have configured. At one point we had the name and version be inputs in the admin, but it felt weird to be able to change the server name and version number on the fly.

[kendelljoseph]

Updated admin to include prompts and resources defined in the config.

example config:

mcpPlugin({
  collections: {},
  mcp: {
    tools: [
      {
        name: 'diceRoll',
        description: 'Rolls a virtual dice with a specified number of sides',
        // ...
      },
    ],
    prompts: [
      {
        name: 'echo',
        description: 'Creates a prompt to process a message',
        // ...
      },
    ],
    resources: [
      {
        name: 'data',
        description: 'Data is a resource that contains special data.',
        // ...
      },
      {
        name: 'dataByID',
        description: 'Data is a resource that contains special data.',
        // ...
      },
    ],
  },

prompts, and resources are now also visible in the admin.

[nick-vogel]

What is the expected behavior of mcp.handlerOptions.basePath? When I update this to '/cms' (for example), I'm not able to connect to the MCP server anymore. I've tried:
claude mcp add --transport http Payload http://127.0.0.1:3000/cms/mcp --header "Authorization: Bearer API-KEY-HERE"

claude mcp add --transport http Payload http://127.0.0.1:3000/cms --header "Authorization: Bearer API-KEY-HERE"
and
claude mcp add --transport http Payload http://127.0.0.1:3000/api/mcp --header "Authorization: Bearer API-KEY-HERE"

But I get a 405 error for each.

Visiting each route (in order) gives me a Next.js 404, Payload CMS 404, and a response that says API key is required.

I'm using the website template on the latest version.

[kendelljoseph]

This option probably shouldn't be available since it isn't configurable right now. It is an artifact of an underlying dependency -- see here.

• MCP server traffic is restricted to the /api/mcp endpoint.

[DudeFactory]

Yes, check some guards, sound like your request catch this middleware.

[jhb-dev]

One improvement that would significantly reduce token usage would be support for Payload’s Select API in the find resource tool. Currently, even when the model only needs to read a small subset of fields, such as the titles of all pages, the full document is queried and returned. This leads to unnecessary token consumption and can exhaust the available budget quickly.

I have created a feature request for this.

[jhb-dev]

Unfortunately, it is currently not possible to query draft versions of documents because the find tool does not expose the draft parameter.

In my case, this is a relevant limitation: I would like to ensure that the agent can only update draft content and is not able to publish anything on its own. However, since the agent cannot read the current draft state, it has no reliable way to work exclusively on drafts.

Update: PR is merged and released in Payload 3.71.

[DudeFactory]

Started using the MCP plugin ~3 days ago (had zero MCP experience before). The main value for me is solving content generation/preparation/sanitization issues — direct structured access to Payload from the website side is awesome.

One problem I hit: MCP updated all records with the same description. I recovered thanks to versions, but I strongly suggest enabling versions by default for any create/update via MCP to avoid accidental mass overwrites.

Also would be great to have more granular update actions (updateOne, updateMany, etc.) so we can restrict bulk operations for safety without complicating the interface.

Overall: it’s great, it works, has bugs, but direction is excellent. I’m building a content planning plugin; if someone has done similar, please share.

Last issue: GitHub Copilot Chat can see MCP tools but not prompts (MCP Inspector sees prompts fine). Might be VS Code related, but flagging here.

Would also love to store prompt/tool metadata inside Payload instead of code in the future so non-devs can manage it.

[jhb-dev]

While testing the MCP plugin with Payload v3.71, I noticed a couple of potential improvements:

1. Virtual fields in create/update schemas
   Virtual fields should be excluded from the create and update schemas. Since they are read-only and cannot be set or updated, including them can be misleading for agents and increases schema noise unnecessarily.

2. Optional returning behavior for create/update tools
   It would be beneficial to add an option such as returning: boolean (default: false) to the create and update tools. This would allow agents to explicitly decide whether the full document should be returned after a mutation.
   This could significantly improve token efficiency and overall performance in cases where the updated document is not needed.
   UPDATE: now possible via select, see feat(plugin-mcp): adds select API with CRUD tools #15301

[kendelljoseph]

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

[jhb-dev]

For us, token consumption is still the biggest challenge when working with the MCP. With larger documents, responses often become too large for the agent to read and process inline, which leads to inefficiencies.

What impacts overall token usage across MCP operations is JSON pretty-printing. At the moment, responses are formatted using JSON.stringify(result, null, 2). In my view, this formatting is unnecessary and increases token usage without adding real value for machine consumption.

I opened a PR to address this here: #15598. I would appreciate your feedback!

[jhb-dev]

I just opened two more feature requests as separate discussions:

• MCP plugin: native OAuth 2.1 authorization server (for claude.ai web custom connectors) #16745
• MCP plugin: expose tool annotations (hints like readOnlyHint) for generated and custom tools #16744

Would appreciate an opinion form the team!