Next
MCP Plugin
This plugin adds Model Context Protocol capabilities.
Core features
- Adds a collection to your config where:
- You can allow / disallow
find,create,update, anddeleteoperations for each collection - You can allow / disallow
findandupdateoperations for each global - You can 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:
1
pnpm add @payloadcms/plugin-mcp
Basic Usage
In the plugins array of your Payload Config, call the plugin with options:
1
import { buildConfig } from 'payload'
2
import { mcpPlugin } from '@payloadcms/plugin-mcp'
3
4
const 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
22
export default config
Options
Option | Type | Description |
|---|---|---|
| | An object of collection slugs to use for MCP capabilities. |
| | An object of collection slugs to use for MCP capabilities. |
| | A description for the collection. |
| | A function that allows you to override the response from the operation tool call. |
| | Determines whether the model can find, create, update, and delete documents in the collection. |
| | Whether to allow the model to find documents in the collection. |
| | Whether to allow the model to create documents in the collection. |
| | Whether to allow the model to update documents in the collection. |
| | Whether to allow the model to delete documents in the collection. |
| | An object of global slugs to expose via MCP. Globals only support find and update. |
| | A description for the global shown to models. |
| | A function that allows you to override the response from the operation tool call. |
| | Determines whether the model can find or update the global. |
| | Whether to allow the model to read the global. |
| | Whether to allow the model to update the global. |
| | Disable the MCP plugin while keeping database schema consistent. |
| | The users collection that API keys are associated with. Defaults to |
| | A function that allows you to override the automatically generated API Keys collection. |
| | Replace the default Bearer-token / API-key auth with a completely custom access strategy. |
| | MCP options that allow you to customize the MCP server. |
| | An array of tools to add to the MCP server. |
| | The name of the tool. |
| | The description of the tool. |
| | The handler function for the tool. |
| | The parameters for the tool (Zod schema). |
| | An array of prompts to add to the MCP server. |
| | The name of the prompt. |
| | The title of the prompt (used by models to determine when to use it). |
| | The description of the prompt. |
| | The handler function for the prompt. |
| | The arguments schema for the prompt (Zod schema). |
| | An array of resources to add to the MCP server. |
| | The name of the resource. |
| | The title of the resource (used by models to determine when to use it). |
| | The description of the resource. |
| | The handler function for the resource. |
| | The URI of the resource (can be a string or ResourceTemplate for dynamic URIs). |
| | The MIME type of the resource. |
| | The handler options for the MCP server. |
| | Whether to log verbose logs to the console (default: false). |
| | The maximum duration for the MCP server requests in seconds (default: 60). |
| | Callback invoked for every MCP event. Useful for analytics and audit logging. |
| | The server options for the MCP server. |
| | The server info for the MCP server. |
| | The name of the MCP server (default: 'Payload MCP Server'). |
| | The version of the MCP server (default: '1.0.0'). |
How Access Control Works with MCP
Step 1 — Enable in your config
Add the collection or global to the plugin with enabled: true (or a capabilities object):
1
mcpPlugin({
2
collections: {
3
posts: { enabled: true },
4
},
5
globals: {
6
'site-settings': { enabled: { find: true, update: true } },
7
},
8
})
Step 2 — Allow in the API Key
In your Payload admin panel, navigate to MCP → API Keys, create a new key, and toggle the individual capabilities on for each collection, global, tool, prompt, and resource you want that key to be able to use.
All MCP requests must include a valid API key as a Bearer token — requests without one are rejected immediately. Here is a complete example of an MCP tools/list request showing the correct headers:
1
curl -i 'http://localhost:3000/api/mcp' \
2
-X POST \
3
-H 'Authorization: Bearer MCP-USER-API-KEY' \
4
-H 'Content-Type: application/json' \
5
-H 'Accept: application/json, text/event-stream' \
6
-d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'
Access controls are also enforced at the Payload level using the user associated with the API key, so existing collection access rules, hooks, and multi-tenant restrictions all continue to apply.
Connecting to MCP Clients
After installing and configuring the plugin, you can connect apps with MCP client capabilities to Payload.
Step 1: Create an API Key
- Start your Payload server
- Navigate to your admin panel at
http://localhost:3000/admin - Go to the MCP → API Keys collection
- Click Create New
- Allow or Disallow MCP traffic permissions for each collection (enable find, create, update, delete as needed)
- Click Create and copy the uniquely generated API key
Step 2: Configure Your MCP Client
MCP Clients can be configured to interact with your MCP server. These clients require some JSON configuration, or platform configuration in order to know how to reach your MCP server.
Our recommended approach to make your server available for most MCP clients is to use the mcp-remote package via npx.
Below are configuration examples for popular MCP clients.
VSCode
1
{
2
"mcp.servers": {
3
"Payload": {
4
"command": "npx",
5
"args": [
6
"-y",
7
"mcp-remote",
8
"http://127.0.0.1:3000/api/mcp",
9
"--header",
10
"Authorization: Bearer MCP-USER-API-KEY"
11
]
12
}
13
}
14
}
Cursor
1
{
2
"mcpServers": {
3
"Payload": {
4
"command": "npx",
5
"args": [
6
"-y",
7
"mcp-remote",
8
"http://localhost:3000/api/mcp",
9
"--header",
10
"Authorization: Bearer MCP-USER-API-KEY"
11
]
12
}
13
}
14
}
Claude Code
1
claude mcp add --transport http Payload http://127.0.0.1:3000/api/mcp \
2
--header "Authorization: Bearer MCP-USER-API-KEY"
Other MCP Clients
For connections without using mcp-remote you can use this configuration format:
1
{
2
"mcpServers": {
3
"Payload": {
4
"type": "http",
5
"url": "http://localhost:3000/api/mcp",
6
"headers": {
7
"Authorization": "Bearer MCP-USER-API-KEY"
8
}
9
}
10
}
11
}
Testing Your MCP Endpoint
The MCP Inspector is the recommended way to explore and test your MCP server interactively:
1
npx @modelcontextprotocol/inspector
Open the inspector, set the URL to http://127.0.0.1:3000/api/mcp, and add an Authorization: Bearer MCP-USER-API-KEY header.
You can also test directly with curl:
1
curl -i 'http://localhost:3000/api/mcp' \
2
-X POST \
3
-H 'Authorization: Bearer MCP-USER-API-KEY' \
4
-H 'Content-Type: application/json' \
5
-H 'Accept: application/json, text/event-stream' \
6
-d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'
Customizations
The plugin supports fully custom prompts, tools and resources that can be called or retrieved by MCP clients. After defining a custom method you can allow / disallow the feature from the admin panel by adjusting the API Key MCP Options checklist.
Globals
Globals are singleton configuration objects (e.g. site settings, navigation). The plugin exposes them as find and update tools — one tool per global per operation.
1
mcpPlugin({
2
globals: {
3
'site-settings': {
4
enabled: {
5
find: true,
6
update: true,
7
},
8
description:
9
'Site-wide configuration settings including name, description, and maintenance mode.',
10
},
11
},
12
})
This produces two MCP tools: findSiteSettings and updateSiteSettings. Globals do not support create or delete because they are singletons managed by Payload.
Prompts
Prompts allow models to generate structured messages for specific tasks. Each prompt defines a schema for arguments and returns formatted messages:
1
prompts: [
2
{
3
name: 'reviewContent',
4
title: 'Content Review Prompt',
5
description: 'Creates a prompt for reviewing content quality',
6
argsSchema: {
7
content: z.string().describe('The content to review'),
8
criteria: z.array(z.string()).describe('Review criteria'),
9
},
10
handler: ({ content, criteria }, req) => ({
11
messages: [
12
{
13
content: {
14
type: 'text',
15
text: `Please review this content based on the following criteria: ${criteria.join(', ')}\n\nContent: ${content}`,
16
},
17
role: 'user',
18
},
19
],
20
}),
21
},
22
]
Resources
Resources provide access to data or content that models can read. They can be static or dynamic with parameterized URIs:
1
resources: [
2
// Static resource
3
{
4
name: 'guidelines',
5
title: 'Content Guidelines',
6
description: 'Company content creation guidelines',
7
uri: 'guidelines://company',
8
mimeType: 'text/markdown',
9
handler: (uri, req) => ({
10
contents: [
11
{
12
uri: uri.href,
13
text: '# Content Guidelines\n\n1. Keep it concise\n2. Use clear language',
14
},
15
],
16
}),
17
},
18
19
// Dynamic resource with template
20
{
21
name: 'userProfile',
22
title: 'User Profile',
23
description: 'Access user profile information',
24
uri: new ResourceTemplate('users://profile/{userId}', { list: undefined }),
25
mimeType: 'application/json',
26
handler: async (uri, { userId }, req) => {
27
// Fetch user data from your system
28
const userData = await getUserById(userId)
29
return {
30
contents: [
31
{
32
uri: uri.href,
33
text: JSON.stringify(userData, null, 2),
34
},
35
],
36
}
37
},
38
},
39
]
Tools
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.
Every tool handler receives (args, req) where req is the full Payload PayloadRequest object. From it you have access to:
Property | Description |
|---|---|
| The initialised Payload instance — use it to call |
| The authenticated user making the request (the MCP API key owner). |
| The active locale, if localisation is enabled. |
| Incoming request headers. |
Always pass req through to Payload operations and set overrideAccess: false so the request inherits the API key owner's access control rules.
1
tools: [
2
{
3
name: 'getPostScores',
4
description: 'Get useful scores about content in posts',
5
handler: async (args, req) => {
6
const { payload } = req
7
const stats = await payload.find({
8
collection: 'posts',
9
where: {
10
createdAt: {
11
greater_than: args.since,
12
},
13
},
14
req,
15
overrideAccess: false,
16
user: req.user,
17
})
18
19
return {
20
content: [
21
{
22
type: 'text',
23
text: `Found ${stats.totalDocs} posts created since ${args.since}`,
24
},
25
],
26
}
27
},
28
parameters: z.object({
29
since: z.string().describe('ISO date string for filtering posts'),
30
}).shape,
31
},
32
]
Reducing Token Usage with select
All collection and global tools accept an optional select parameter. It limits which fields are returned in the response, which can significantly reduce token consumption when working with large documents.
select is a JSON string that follows Payload's Select API syntax — set a field to true to include it:
1
// In a tool call, pass select as a JSON string:
2
// arguments: { select: '{"title": true, "slug": true}' }
For example, to list only post titles:
1
curl -i 'http://localhost:3000/api/mcp' \
2
-X POST \
3
-H 'Authorization: Bearer MCP-USER-API-KEY' \
4
-H 'Content-Type: application/json' \
5
-H 'Accept: application/json, text/event-stream' \
6
-d '{
7
"jsonrpc": "2.0",
8
"id": "1",
9
"method": "tools/call",
10
"params": {
11
"name": "findPosts",
12
"arguments": {
13
"select": "{\"title\": true, \"slug\": true}"
14
}
15
}
16
}'
Without select, the full document is returned for every result. On collections with many fields or rich text, this can exhaust a model's context budget quickly.
Modifying Responses
Use overrideResponse on a collection or global to intercept what is sent back to the model after any operation. This is the primary place to sanitize sensitive data.
1
mcpPlugin({
2
collections: {
3
posts: {
4
enabled: true,
5
overrideResponse: (response, doc, req) => {
6
req.payload.logger.info('[MCP] Post response intercepted')
7
8
// Append additional context
9
response.content.push({
10
type: 'text',
11
text: `Document last modified by: ${doc.updatedBy ?? 'unknown'}`,
12
})
13
14
return response
15
},
16
},
17
users: {
18
enabled: { find: true },
19
overrideResponse: (response, doc, req) => {
20
// Redact sensitive fields before the model sees the document
21
response.content = response.content.map((item) => ({
22
...item,
23
text: item.text
24
.replace(/"hash":\s*"[^"]*"/g, '"hash": "[redacted]"')
25
.replace(/"salt":\s*"[^"]*"/g, '"salt": "[redacted]"'),
26
}))
27
return response
28
},
29
},
30
},
31
})
API Key Access to MCP
Payload adds an API key collection that allows admins to manage MCP capabilities. Admins can:
- Create user associated API keys for MCP clients
Allowordisallowendpoint traffic in real-timeAllowordisallowtools, resources, and prompts
You can customize the API Key collection using the overrideApiKeyCollection option:
1
mcpPlugin({
2
overrideApiKeyCollection: (collection) => {
3
// Add fields to the API Keys collection
4
collection.fields.push({
5
name: 'department',
6
type: 'select',
7
options: [
8
{ label: 'Development', value: 'dev' },
9
{ label: 'Marketing', value: 'marketing' },
10
],
11
})
12
13
// You can also add hooks
14
collection.hooks?.beforeRead?.push(({ doc, req }) => {
15
req.payload.logger.info('Before Read MCP hook!')
16
return doc
17
})
18
return collection
19
},
20
// ... other options
21
})
You can create an MCP access strategy using the overrideAuth option:
1
import { type MCPAccessSettings, mcpPlugin } from '@payloadcms/plugin-mcp'
2
3
// ... other config
4
5
mcpPlugin({
6
overrideAuth: (req, getDefaultMcpAccessSettings) => {
7
const { payload } = req
8
9
// This will return the default MCPAccessSettings
10
// getDefaultMcpAccessSettings()
11
12
payload.logger.info('Custom access Settings for all MCP traffic')
13
return {
14
posts: {
15
find: true,
16
},
17
products: {
18
find: true,
19
},
20
} as MCPAccessSettings
21
},
22
// ... other options
23
})
If you want the default MCPAccessSettings, you can use the additional argument getDefaultMcpAccessSettings. This will use the Bearer token found in the headers on the req to return the MCPAccessSettings related to the user assigned to the API key.
Hooks
To understand or modify data returned by models at runtime use a collection Hook. Within a hook you can look up the API context. If the context is MCP that collection was triggered by the MCP Plugin. This does not apply to custom tools or resources that have their own context, and can make unrelated database calls.
In this example, Post titles are modified to include '(MCP Hook Override)' when they are read using MCP.
1
import type { CollectionConfig } from 'payload'
2
3
export const Posts: CollectionConfig = {
4
slug: 'posts',
5
fields: [
6
{
7
name: 'title',
8
type: 'text',
9
admin: {
10
description: 'The title of the post',
11
},
12
required: true,
13
},
14
15
// ... other fields
16
],
17
hooks: {
18
beforeRead: [
19
({ doc, req }) => {
20
if (req.payloadAPI === 'MCP') {
21
doc.title = `${doc.title} (MCP Hook Override)`
22
}
23
return doc
24
},
25
],
26
},
27
}
Localization
When your Payload config has localization enabled, all collection and global tools automatically include locale and fallbackLocale parameters — no extra plugin configuration is required.
Parameter | Description |
|---|---|
| Retrieve or write data in a specific locale (e.g. |
| The locale to use when the requested locale has no translation for a field. |
Example — find posts in Spanish with English as fallback:
1
curl -i 'http://localhost:3000/api/mcp' \
2
-X POST \
3
-H 'Authorization: Bearer MCP-USER-API-KEY' \
4
-H 'Content-Type: application/json' \
5
-H 'Accept: application/json, text/event-stream' \
6
-d '{
7
"jsonrpc": "2.0",
8
"id": "1",
9
"method": "tools/call",
10
"params": {
11
"name": "findPosts",
12
"arguments": {
13
"locale": "es",
14
"fallbackLocale": "en"
15
}
16
}
17
}'
Tracking MCP Events
Use the onEvent callback to receive a notification for every MCP request processed by your server. This is useful for analytics, audit logging, or debugging.
1
mcpPlugin({
2
mcp: {
3
handlerOptions: {
4
onEvent: (event) => {
5
// Forward to your analytics pipeline, audit log, etc.
6
console.log('[MCP event]', event)
7
},
8
},
9
},
10
})
Virtual Fields
Virtual fields (computed, read-only fields) are automatically excluded from the create and update tool schemas. They cannot be set by a model, so including them in the schema would be misleading and add noise. They are still present in find responses.
Performance
There are several levers for reducing the number of tokens consumed per MCP request. Token efficiency matters because large responses can exhaust a model's context budget, slow down responses, and increase cost.
Write strong descriptions
The description you provide for a collection or global is the primary signal a model uses to decide which tool to call. A vague description leads to missed or incorrect tool calls; a precise description gets the right tool called on the first try.
1
// Weak — a model has no idea what kind of posts these are or when to use this collection
2
mcpPlugin({
3
collections: {
4
posts: {
5
enabled: true,
6
description: 'My posts',
7
},
8
},
9
})
10
11
// Strong — the model understands the content and its purpose
12
mcpPlugin({
13
collections: {
14
posts: {
15
enabled: true,
16
description:
17
'Published articles covering science and nature topics, with title, body, tags, and publication date.',
18
},
19
},
20
})
Use select to return only the fields you need
By default, the full document is returned for every operation. On collections with many fields, rich text, or deeply nested relationships this can be very large. Pass a select JSON string to limit what comes back:
1
# Return only title and slug instead of the full document
2
-d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"findPosts","arguments":{"select":"{\"title\": true, \"slug\": true}"}}}'
See Reducing Token Usage with select for more detail.
Sanitize responses with overrideResponse
If a collection has fields that are irrelevant or sensitive for the model's task, strip them before the response leaves the server. Fewer fields returned means fewer tokens consumed on every call.
See Modifying Responses for examples.
Only enable the operations you need
If a model only needs to read data, enable only find. Every additional operation (create, update, delete) adds more tools to the model's context, which costs tokens and increases the chance of an unintended action.
1
mcpPlugin({
2
collections: {
3
posts: {
4
enabled: { find: true }, // create / update / delete are off
5
},
6
},
7
})