PayloadCMS

Payload 4 MCP: the guide to letting an assistant act on your content

Connect Payload 4 MCP, decide what your assistant is allowed to do, and give it the instructions it reads before it touches your site content.


6 min read
mcp payload 4.0

Updating ten entries, publishing an article prepared the day before, filing media in the right category: small tasks, but they add up. Payload 4 MCP changes that. Your AI assistant connects to the site and does those tasks itself, inside the frame you set. This guide shows how to connect it, what the assistant is allowed to do, and which instructions it reads before it writes.

At Beease, we turn MCP on for almost every client project, especially new ones. It has even become one of the arguments that matter most when we present a site. Here is the setup we use.

What you get an assistant to do with Payload 4 MCP

In one sentence: MCP lets your assistant call your Payload site directly.

In practice, the assistant can read your content structure, search for documents, create them, edit them, and upload files. It does not guess the shape of a page. It asks the site for the collection schema, then fills the fields the way an editor would in the admin.

For a marketing lead, the benefit is simple: a request in plain language (“update the event dates on the three relevant pages”) becomes an action on the site, with no copy-paste between a document and the admin. For a project lead, it is a way to move batches of content (imports, bulk fixes, translations to review) without redoing them by hand.

The assistant does not bypass the CMS. It goes through the same collections, the same fields, and the same rules as your editors. That is what keeps the result clean.

What changes compared with the Payload 3 MCP

If you already used MCP on a Payload 3 site, the logic stays the same. Setup, though, is much lighter.

In version 3, each collection was turned on by hand, with its own tools and a key to create. Instructions for the assistant lived in the config, so on the developer side.

In Payload 4, everything goes through generic tools that work for every collection and every global: getConfigInfo, getCollectionSchema, findDocuments, createDocuments, updateDocument, deleteDocuments, getUploadInstructions, getGlobalSchema, findGlobal, updateGlobal. The assistant discovers the site instead of depending on a list prepared by hand.

Payload 3

Payload 4

MCP

Activation

Collection by collection in the config

mcpPlugin({}) covers collections and globals

Tool names

One tool per collection (findPosts…)

Generic tools (findDocuments…)

Key / connection

API Keys collection, Bearer header

OAuth login, or a key carried by the user

Instructions

Descriptions in the plugin config

llmInstructions, editable in the admin

Files

No dedicated upload flow

The agent uploads files itself

Two changes matter day to day: instructions can be edited in the admin, and the agent can now upload files itself.

Connect the plugin and your client

On the site side, one line in the Payload config is enough:

1 2 3 4 5 6 7 import { buildConfig } from 'payload' import { mcpPlugin } from '@payloadcms/plugin-mcp' export default buildConfig({ // collections, globals, db… plugins: [mcpPlugin({})], })

On the assistant side, you declare an MCP server of type http. On a development machine, the client points at the local site:

1 2 3 4 5 6 7 8 { "mcpServers": { "payload": { "type": "http", "url": "http://127.0.0.1:3000/api/mcp?overrideAccess=true" } } }

The overrideAccess=true parameter skips access control: handy locally, with no key to create. This is the mode we gladly use while building a site, and it works for us as is.

On the live site, you drop that parameter (the server rejects that URL outside development). You then sign in as usual. Without authentication, the server offers an OAuth login, on by default: you sign in to the Payload admin, you authorize the client, and the token you receive is only for MCP.

If you prefer a key, it now lives on the user, with auth.useAPIKey on the auth collection. The client then sends the header Authorization: users API-Key followed by the key, where users is the slug of that collection. There is no longer a separate collection for MCP keys.

In short: you move from the dev machine to the live site, and the connection changes with you.

Open content, close deletion and accounts

This is where tutorials stop and the settings make the difference.

By default, mcpPlugin({}) exposes every collection. Our reflex at Beease is not to lock everything down out of caution. It is the opposite: open as much content as possible, so the agent does the work itself. A closed collection is an action that will come back to someone, by hand.

The Beease rule: open content as widely as possible (pages, articles, media, categories, editorial settings) so the agent can publish, update, and file without manual rework. Often close deletion and the accounts collection.

In practice, that looks like a config of this kind:

1 2 3 4 5 6 7 8 9 10 mcpPlugin({ collections: { pages: { tools: { delete: false } }, posts: { tools: { delete: false } }, users: { tools: { create: false, update: false, delete: false }, // login, auth, forgotPassword… restent fermés tant qu'on ne les passe pas à true }, }, })

Why close delete? Because a deletion is rarely urgent, and it is easy to do in the admin. The agent creates, corrects, and enriches. The decision to remove content stays human.

Why the users collection? Because it does not hold editorial content. Auth tools (login, auth, forgotPassword, resetPassword, unlock, verify) are already closed until you turn them on. We do not turn them on.

The access option remains a possible setting. It is neither required nor our usual choice.

Write the instructions the agent reads before it acts

An assistant that is well connected but poorly briefed produces content that is technically valid and editorially off. The llmInstructions field fixes that.

It sits on a collection or a global, in Markdown. When the agent calls getCollectionSchema or getGlobalSchema, it receives those instructions with the schema. It therefore has to read them before creating or editing anything.

1 2 3 4 5 6 7 8 9 10 11 12 13 import type { CollectionConfig } from 'payload' export const Posts: CollectionConfig = { slug: 'posts', llmInstructions: ` - Garder les blocs de mise en page prévus pour les articles, ne pas en inventer. - Titres courts, un seul message par titre. - Remplir l'extrait et les champs SEO à chaque création. `, fields: [ // … ], }

The value set in code is the starting point. After that, the content team adjusts it directly in the admin, via “Edit LLM instructions”. That is the right place for your editorial guidelines, applied to each collection: tone, title length, allowed blocks, fields that must never stay empty.

Create, edit, upload a file

Once connected, the agent creates content, corrects it, and uploads files. It can handle several at once, or find a series of pages and update them one by one.

Is your site multilingual? It reads and writes in the requested language, following your multilingual content.

For a file, a URL that is already online or an attachment is enough: the agent uploads it to the media library and attaches it to the content.

Have it installed on your site

Payload 4 MCP takes very little configuration. What makes the difference is the choices around it: which collections to open, what to close, how to move from local to the live site, and above all which instructions to give the agent so the content it produces follows your guidelines.

That is what we set up on our projects, and we can do it on yours: a demo to see an assistant act on a Payload site, or the installation and setup of MCP directly on yours.


Jeune homme aux cheveux bruns courts, portant des lunettes rondes et une chemise bleue, souriant légèrement devant un fond neutre

Book a demo with Martin

MCP

Payload 4

Martin shows you an assistant that publishes, corrects, and files assets on a Payload site. Then we look at what that would look like on yours.

arrowSchedule a call


Planning a redesign or a new site? See our support for Payload CMS sites, with MCP planned from launch.