如何用 Payload MCP 插件把内容数据暴露给 MCP 客户端（/api/mcp）

如何用 Payload MCP 插件把内容数据暴露给 MCP 客户端（/api/mcp）

【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload

如果你的 Payload 项目里已经配好了 collections 和 globals，想让 Cursor、Claude Code、VSCode 这类 MCP 客户端直接查询或增删改你的内容数据，@payloadcms/plugin-mcp就是官方给出的路径。装上插件并把mcpPlugin加进 Payload 配置后，POST /api/mcp会接受 JSON-RPC 2.0 的 MCP 请求，所有 collection 和 global 通过一组通用工具（getConfigInfo、getCollectionSchema、findDocuments、createDocuments、updateDocument、deleteDocuments、getGlobalSchema、findGlobal、updateGlobal等）暴露出去，并受 Payload 的访问控制约束。本文的目标是完成这条链路：安装插件 → 注册到配置 → 连接 MCP 客户端 → 用 curl 或 MCP Inspector 验证端点可用。前提是一个可启动的 Payload 项目；开发环境下可用overrideAccess=true快速跑通，生产环境则需要发送 Payload 授权（用户 API key）。

安装与插件注册

在 Payload 项目根目录安装插件：

pnpm add @payloadcms/plugin-mcp

然后在 Payload 配置的plugins数组中加入mcpPlugin，这一步完成/api/mcp端点的注册：

import { buildConfig } from 'payload' import { mcpPlugin } from '@payloadcms/plugin-mcp' export default buildConfig({ // your collections, globals, etc. plugins: [mcpPlugin({})], })

插件参数为空时即可工作，所有 collection 和 global 都会通过内置工具暴露。启动 Payload 后，HTTP 端点即可用；开发阶段配置变更遵循 Payload 正常的 dev-server 重载周期。

连接 MCP 客户端

HTTP（streamable HTTP）传输是官方推荐的本地开发和部署方式，连接方式分两种：

开发环境：跳过访问控制

开发时把客户端 URL 指向带overrideAccess=true的地址即可跳过 Payload 访问控制：

{ "mcpServers": { "Payload": { "type": "http", "url": "http://127.0.0.1:3000/api/mcp?overrideAccess=true" } } }

这个 URL 只在开发时有效：非开发环境下端点会直接拒绝overrideAccessURL 参数（返回 400，错误信息为MCP overrideAccess is only available in development.，见 endpoint 实现），参数值也只接受true或false两种。

生产环境：发送 Payload 授权

离开开发环境后，去掉overrideAccess=true，改为在请求头中发送 Payload 授权。MCP 端点使用 Payload 的认证体系，用户 API key 的头部格式为：

Authorization: <authCollectionSlug> API-Key <key>

API key 的获取步骤（来自 API Key Strategy 文档）：

1. 确认目标 auth collection 开启了useAPIKey：

import type { CollectionConfig } from 'payload' export const Users: CollectionConfig = { slug: 'users', auth: { useAPIKey: true, }, fields: [], }

2. 启动 Payload，打开 admin 面板，进入该 collection 中某个用户文档；
3. 为该用户启用 API key 认证、生成并复制 key，然后保存；
4. 在客户端配置中写成Authorization: users API-Key <key>，其中users换成你实际 auth collection 的 slug。

API key 在数据库中是加密存储的；如果更换了PAYLOAD_SECRET，已有的 API key 会失效，需要重新生成。

如果客户端原生支持 HTTP 传输，可以直接写：

{ "mcpServers": { "Payload": { "type": "http", "url": "http://localhost:3000/api/mcp", "headers": { "Authorization": "users API-Key MCP-USER-API-KEY" } } } }

MCP-USER-API-KEY是文档示例占位值，替换为你按上面步骤生成的真实 key。

不支持原生 HTTP 的客户端可以用mcp-remote作为适配器，例如 Cursor 的配置：

{ "mcpServers": { "Payload": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:3000/api/mcp", "--header", "Authorization: users API-Key MCP-USER-API-KEY" ] } } }

Claude Code 则可以用命令行添加：

claude mcp add --transport http Payload http://127.0.0.1:3000/api/mcp \ --header "Authorization: users API-Key MCP-USER-API-KEY"

这些 JSON 配置结构可能随客户端版本变化，以客户端官方文档为准。

验证端点：curl 与 MCP Inspector

最快的手动验证是用 curl 发一个tools/list请求，端点注册成功且授权通过时，会返回该客户端可见的工具列表：

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

交互式探索推荐用 MCP Inspector：

npx @modelcontextprotocol/inspector

把 URL 设为http://127.0.0.1:3000/api/mcp，并加上Authorization: users API-Key MCP-USER-API-KEY请求头，就可以逐个调用工具。

跑通后的典型使用顺序是：先调getConfigInfo查看当前客户端可见的 collection 与 global slug，再用getCollectionSchema检查某个 collection 的字段结构，然后用findDocuments查询、createDocuments创建文档。createDocuments和updateDocument默认只返回受影响的文档 ID，需要完整文档时传returning: true，再配合select控制返回字段；findDocuments、findGlobal、updateGlobal则直接接受select。带富文本或深层关系的 collection 不传select会返回完整文档，容易消耗模型的上下文预算，这是文档明确给出的性能建议。

授权行为与限制

几个直接影响能否跑通的规则，均来自插件源码与文档：

• 默认 MCP access 要求有登录用户。插件默认 access 回调是Boolean(req.user)（见 defaultAccess），没有发送授权时 MCP 以“无用户”身份运行访问控制，大部分内置工具不会出现在工具列表里。文档中的客户端示例都带了授权，原因在此。
• 发送了 Authorization 但认证失败会直接报错。端点在收到Authorization头后走 Payload 正常认证，若解析不出用户会抛出未授权错误（见 access 实现）。此时先检查 header 里 collection slug 是否与实际 auth collection 一致、key 是否有效、PAYLOAD_SECRET是否变动过。
• overrideAccess=true仅限开发环境，它跳过 item access 回调、内置权限检查以及内置 handler 内的 Payload 访问控制；生产环境请走真实授权。
• 虚拟字段不出现在getCollectionSchema/getGlobalSchema中（它们只读且模型无法设置），但仍会出现在 find 响应里，这是预期行为。
• 模型默认收到完整文档，文档明确要求在敏感字段进入模型前用select或overrideResponse剔除，overrideResponse可按 collection 或单个内置工具配置，解析顺序为 per-tool > collection/global > 内置默认。
• 客户端只能通过 stdio 拉起本地进程时，插件也提供payload-mcpbin（npx payload-mcp，可用环境变量PAYLOAD_MCP_AUTHORIZATION传同一个授权值）。但它是有限制的传输：配置、注册与授权只在启动时初始化一次，改配置或权限后必须重启 server 并重连客户端，且每个客户端各起一个独立 Payload 进程，官方推荐一律用 HTTP。
• 内置工具在请求上会设置req.payloadAPI === 'MCP'（见 endpoint 实现），你可以在 collection hook 里据此识别 MCP 流量；自定义工具自行发起 local API 调用时，req.payloadAPI由你控制。

下一步

端点验证通过后，按文档的 MCP Plugin 可以继续：用collectionsmap 关闭不需要的内置操作（如tools: { delete: false }）、给 auth collection 显式开启login/auth等 opt-in 工具、用defineTool/defineCollectionTool定义自定义工具，以及给 upload collection 配置getUploadInstructions走文件上传流程。源码位于 packages/plugin-mcp，实现细节（授权过滤、item access 检查）可对照src/endpoint/access.ts与src/mcp/下的内置工具查看。

【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload