You’ve heard that Payload “does MCP”, and you want to know what that means for your project. What it means depends on what you want the AI to do. Payload’s official MCP plugin lets an AI assistant, such as Claude or Gemini, read and change the content in your Payload site, and it has been on npm since 23 October 2025. Writing Payload code with AI is a different job, and Payload ships a different tool for it.
This guide covers both jobs. It sets up the plugin step by step, shows how to keep the AI inside the lines you draw, and explains what to use when you want AI to write the code itself. It’s written from how we build on Payload, and as of September 2026 we manage 27 Payload codebases, all built on Next.js.
- What is MCP in Payload?
- Two jobs people mean by “Payload MCP”
- How to set up the Payload MCP plugin
- What the AI can and cannot touch
- Keep MCP token use down
- Beyond reading and writing: custom tools, prompts and resources
- For writing Payload code, use skills
- Why Payload suits AI-powered development
- What’s next: Payload 4.0 and Figma
- Payload MCP: common questions
- What to do next
What is MCP in Payload?
MCP in Payload is a plugin that turns your collections and globals into tools an AI assistant can call. The Model Context Protocol is an open standard Anthropic open-sourced in November 2024, and it gives assistants one common way to use another system’s tools. Payload’s plugin serves those tools from your own site, at /api/mcp, so any MCP client with the right key can reach them.
Each collection you enable becomes a set of tools for find, create, update and delete. Globals, such as site settings or the main navigation, get find and update only. The assistant reads the tool list, decides which one fits your request, and calls it, and Payload runs the operation as it would for any other request.
For example, a marketing lead wants every blog post without a meta description found and given a draft one. With the plugin enabled on posts, they can ask their AI assistant to do it in plain language, and the assistant calls the find tool, reads the posts, writes the descriptions and calls update on each one. We’ll build that setup through this guide.
If you’re weighing MCP against building an automated workflow, our guide to AI automation sets out when an assistant over MCP is the better route.
Two jobs people mean by “Payload MCP”
People searching for Payload and MCP usually want one of two things. Some want an assistant to work with the content inside a running Payload site. Others want an AI coding tool to write correct Payload code while they build. Payload serves the two jobs with different tools:
| Job | What the AI touches | What Payload ships for it | Where it runs |
|---|---|---|---|
| Work with your content | Documents in your collections and globals | The official MCP plugin, @payloadcms/plugin-mcp | Your deployed site or a local copy, at /api/mcp |
| Write your Payload code | Your config, collections, fields, hooks and access rules | Payload’s agent skills, and a Claude Code plugin | Your editor or terminal |
Most of this guide covers the first job, because that’s what the MCP plugin does. The section on skills covers the second, including the community MCP servers that still rank for it.
How to set up the Payload MCP plugin
Six steps take you from install to a working, tested connection:
- Install the plugin and enable one collection
- Make the API Keys collection visible
- Create a key and allow its capabilities
- Connect your MCP client
- Test the connection before you trust it
- Write descriptions the model can act on
1. Install the plugin and enable one collection
Add the package with pnpm add @payloadcms/plugin-mcp, then add mcpPlugin to the plugins array in your Payload config. Start with one collection and one operation, so you can see exactly what the assistant can do before you give it more.
For example, the marketing setup starts with read-only access to posts:
import { buildConfig } from 'payload'
import { mcpPlugin } from '@payloadcms/plugin-mcp'
export default buildConfig({
// ...collections and the rest of your config
plugins: [
mcpPlugin({
collections: {
posts: {
enabled: { find: true },
description: 'Published blog posts, with title, slug, body, author and SEO meta description.',
},
},
}),
],
})Update comes later, once the find calls return what you expect. The plugin’s full list of options covers globals, custom tools and the rest.
2. Make the API Keys collection visible
The plugin adds an API Keys collection, and it starts locked. The generated collection denies admin panel, REST and GraphQL access until you set its access rules with overrideApiKeyCollection, so you won’t see it in the admin panel at first.
In practice, you decide who may issue keys. By default, a signed-in user can create and manage only their own keys. If administrators should issue keys for other people, the docs show how to give that right to an admin role only, on both the collection and its user field. Keep that group small, because a key acts as the person it belongs to.
3. Create a key and allow its capabilities
Open MCP, then API Keys, in the admin panel and create a key. On the key, you toggle each capability the plugin exposes, per collection, global, tool, prompt and resource, then copy the generated key.
Enabling a collection in the config and allowing it on a key are separate steps, and both have to happen. For example, the marketing lead’s key gets find on posts and nothing else for now, even if the config later enables more.
4. Connect your MCP client
Your assistant needs your server’s address, which is your site’s URL followed by /api/mcp, and the key, sent as a Bearer token. While you develop, the address is http://localhost:3000/api/mcp. In Claude Code, one command adds it:
claude mcp add --transport http Payload https://your-site.com/api/mcp \
--header "Authorization: Bearer MCP-USER-API-KEY"Cursor and VS Code connect through the mcp-remote package, with the same address and header in their MCP JSON. Clients that speak HTTP directly take a short config with "type": "http", the URL and the header. The docs give the exact JSON for each, and they warn that client formats change, so check your client’s own docs if a config stops working.
5. Test the connection before you trust it
Run the MCP Inspector with npx @modelcontextprotocol/inspector, point it at your server’s /api/mcp address, and add the Authorization header. It lists every tool your key can see, and you can call each one by hand.
For example, the marketing key should show a find tool for posts and nothing that writes. If an update or delete tool appears, go back to the key before you connect anyone’s assistant. A tools/list call with curl gives the same answer without the interface.
6. Write descriptions the model can act on
The description on each collection is the main thing a model reads when it picks a tool. A vague one leads to the wrong tool or a missed call, and a precise one gets the right call the first time.
For example, “My posts” tells the model nothing. “Published blog posts, with title, slug, body, author and SEO meta description” tells it what’s inside and when to use it. Once find works, enable update on posts in the config and allow it on the marketing key, and the meta description job can run end to end.
What the AI can and cannot touch
The assistant can touch only what passes three gates. The config has to enable the operation, the key has to allow it, and Payload’s own access control has to permit it for the key’s owner. All MCP requests need a valid key, and requests without one are rejected.
Requests made with a key act as its owner, so your existing collection access rules and hooks still apply. If you run several sites or brands from one install, each key also inherits the tenant rules, and our guide to Payload multi-tenancy covers how those are set. In custom tools, the docs tell you to pass req through and turn overrideAccess off, so the tool runs under the same rules as everything else.
Fields you compute rather than store, which Payload calls virtual fields, are left out of the create and update tools, so a model can’t set them. It does see the whole document by default, though. Trim what it sees with select or overrideResponse before personal or sensitive fields ever reach the model.
For example, in an e-commerce admin build, the blanket rule is no deletes, on any key, even though the plugin allows them. Create stays switched off wherever creating a record sets off something that can’t be undone, such as an outgoing email. Read is the grant given most often, across collections that hold no personal data. Each collection is still a separate choice, so the grants differ from one collection to the next.
For the marketing key, that means find and update on posts, and nothing else. If the assistant tries to delete a post, there’s no delete tool for it to call. If your team wants help deciding who holds which keys and what each one can reach, our Payload development team sets up access as part of a build.
Keep MCP token use down
Every tool call sends data into the model’s context, and large documents fill it fast. That slows answers, raises the bill for model usage, and can push earlier instructions out of the model’s view. The plugin gives you four ways to keep it lean.
- Select only the fields you need. Every collection and global tool accepts a
selectparameter in Payload’s Select API syntax. For example,{"title": true, "slug": true}returns two fields instead of a whole post with its rich text body. - Trim responses on the server.
overrideResponsestrips fields before the response leaves Payload, on every call, whatever the model asks for. - Enable only the operations you need. Each extra operation adds more tools to the model’s context, which costs tokens and raises the chance of an action you didn’t intend.
- Write strong descriptions. A model that picks the right tool first time doesn’t spend tokens on wrong ones.
The plugin can also report every request through the onEvent callback. For example, you can send each event to your audit log and see which keys call which tools, and how often.
Beyond reading and writing: custom tools, prompts and resources
When find, create, update and delete aren’t enough, you extend the plugin with your own tools. A custom tool has a name, a description, parameters defined with Zod, and a handler that receives the full Payload request. For example, the docs build a tool that counts posts created since a given date, which a model couldn’t work out efficiently by paging through every post.
Prompts and resources cover the rest. A prompt packages a request your team makes often, and a resource hands the model reference material it can read. If your config uses localisation, every collection and global tool also takes locale and fallbackLocale, with no extra setup.
For example, on an e-commerce build, with the plugin set up properly and extended with custom tools, store admins work through the assistant they already use, such as Claude or Gemini, and get a great deal done from one conversation. A custom tool can answer a question that spans orders and products in one call, where the built-in tools would need several.
How each assistant connects differs. Claude Code and Gemini CLI send the key as a header, as in step 4. ChatGPT’s connectors can’t present a custom API key and sign in with OAuth or no authentication, so connecting ChatGPT means putting an OAuth sign-in in front of the endpoint, and the plugin’s overrideAuth option lets you replace the key check with your own. Our Payload use cases show more of what teams build once AI can reach their content.
For writing Payload code, use skills
If you want AI to write your Payload code, use Payload’s agent skills. A skill gives the model Payload’s own rules for collections, fields, hooks and access control, so it writes config Payload accepts and uses the features Payload already has.
Payload publishes two skills in payloadcms/skills, a public repository it has run since January 2026. The payload skill covers building with Payload, and the cms-migration skill plans a move from another CMS, which our checklist for migrating to Payload walks through. Payload is also moving the payload skill into the payload package itself, at node_modules/payload/skills/payload/, so the guidance matches the version you’ve installed (PR #17652, merged on 6 August 2026).
As of 28 September 2026 that ships in the 4.0 canary builds only, so on stable 3.x you install the skill from payloadcms/skills. New 4.0 projects made with create-payload-app also get an AGENTS.md and a CLAUDE.md at the root that point the assistant at the skill. If you use Claude Code, Payload’s main repository has also carried a Claude Code plugin since 30 October 2025, which installs the same guidance from the latest code.
Several community MCP servers rank for “Payload MCP” with this second job in mind. The most visible is the Payload CMS 3.0 MCP Server, which validates code, generates templates and scaffolds projects. Its last commit was on 15 March 2025, so it predates Payload’s skills and doesn’t reflect the releases since.
Your project’s own rules sit alongside the skills. A CLAUDE.md or AGENTS.md file, or Cursor rules, tells the model how your codebase is laid out and what your team has decided, and the skills tell it how Payload works. For the docs themselves, Payload publishes llms.txt files split by major version, so a model reads the 3.x docs for a 3.x project. In practice, many teams run both tools, the skills while they build and the MCP plugin once the site is live.
Why Payload suits AI-powered development
Payload suits AI-powered development because its config is strict and still flexible. Everything from collections to access rules is typed code, so a model works inside a shape Payload validates, and it has less room to invent its own approach. Guardrails matter most when you build with AI, so wherever you can limit a model’s room to invent concepts, features or methods, you enforce that limit.
AI-powered development took off for us with the release of stable frontier models such as Claude Opus 4.5 in November 2025, and every release since has moved it further. That includes open models as well as closed ones. As of September 2026, the frontier includes Claude Opus 5.5 and Fable 5.1, and open-weight models such as Zhipu AI’s GLM-5.3.
A spec-driven workflow is one way we keep the build bill down. Spec-driven development is an established, widely used method, and we didn’t invent it. It carries a change through requirements gathering, design, task breakdown and implementation, then unit, integration and end-to-end tests and an acceptance check before the change is done. Amazon’s Kiro, an agentic development environment from AWS, is built around specs and is a good place to start. Within that flow, a frontier model gathers the requirements, writes the design and breaks the work into tasks, and an equally capable lower-cost model, such as GLM-5.3, does the implementation. Not every change needs that much process. Adding a field doesn’t.
For example, a new product collection goes through requirements, design and tasks before any code is written, with the payload skill loaded so the tasks use Payload’s own field types. The implementation model then works task by task, and the config tells it immediately when a field or relationship doesn’t fit.
What’s next: Payload 4.0 and Figma
Payload 4.0 aims to make MCP work out of the box. Payload’s 4.0 preview, published on 9 June 2026, sets the goal as “add the MCP plugin, configure MCP JSON, and go”. It plans tools that are on by default and switched off by choice, a simpler local setup, better API key screens, and support for project-specific instructions.
As of 28 September 2026, 4.0 is still in canary releases (4.0.0-canary.37, published on 24 September), and the current stable release is 3.90.2. Until 4.0 is stable, you set MCP up by hand as described above, so keep any setup scripts small, because 4.0 aims to make them unnecessary.
Payload joined Figma, and our guide to the Figma acquisition covers what’s been said and shipped so far. We expect design to come closer to Payload next. Figma is the tool most teams design in, so a design experience synced into Payload, at the level of components or design tokens, perhaps through something like Figma Make, is the obvious next step, and it’s the one we’d most like to see.