如何用 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 项目开发环境下可用overrideAccesstrue快速跑通生产环境则需要发送 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 客户端HTTPstreamable HTTP传输是官方推荐的本地开发和部署方式连接方式分两种开发环境跳过访问控制开发时把客户端 URL 指向带overrideAccesstrue的地址即可跳过 Payload 访问控制{ mcpServers: { Payload: { type: http, url: http://127.0.0.1:3000/api/mcp?overrideAccesstrue } } }这个 URL 只在开发时有效非开发环境下端点会直接拒绝overrideAccessURL 参数返回 400错误信息为MCP overrideAccess is only available in development.见 endpoint 实现参数值也只接受true或false两种。生产环境发送 Payload 授权离开开发环境后去掉overrideAccesstrue改为在请求头中发送 Payload 授权。MCP 端点使用 Payload 的认证体系用户 API key 的头部格式为Authorization: authCollectionSlug API-Key keyAPI key 的获取步骤来自 API Key Strategy 文档确认目标 auth collection 开启了useAPIKeyimport type { CollectionConfig } from payload export const Users: CollectionConfig { slug: users, auth: { useAPIKey: true, }, fields: [], }启动 Payload打开 admin 面板进入该 collection 中某个用户文档为该用户启用 API key 认证、生成并复制 key然后保存在客户端配置中写成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 Inspectornpx 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是否变动过。overrideAccesstrue仅限开发环境它跳过 item access 回调、内置权限检查以及内置 handler 内的 Payload 访问控制生产环境请走真实授权。虚拟字段不出现在getCollectionSchema/getGlobalSchema中它们只读且模型无法设置但仍会出现在 find 响应里这是预期行为。模型默认收到完整文档文档明确要求在敏感字段进入模型前用select或overrideResponse剔除overrideResponse可按 collection 或单个内置工具配置解析顺序为 per-tool collection/global 内置默认。客户端只能通过 stdio 拉起本地进程时插件也提供payload-mcpbinnpx 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
