在 Cursor 中使用 Crispy（Payload MCP）操作 CMS

Crispy 3 基于 Payload CMS 内置的 @payloadcms/plugin-mcp 暴露 POST /api/mcp 端点。配置好 Cursor 的 MCP 后，你可以在对话里直接用自然语言读写文章、分类、标签、Globals、缓存等内容，无需手写脚本或打开 Admin。

1. 前置条件

• Crispy 服务可访问：本地 pnpm cli dev:dev（默认 http://localhost:3333）；也可指向已部署的线上站点，只要 POST /api/mcp 能连通即可
• 已获取 MCP API Key：本地 pnpm cli mcp:key 或 db:seed；线上在 Admin → MCP → API Keys 创建
• Key 关联 editor 用户，并在 API Key 中开启所需 Collection / Global / 自定义 tool 权限
• 生产 PostgreSQL 若启用 Globals / 自定义 tools，需先执行 pnpm cli db:migrate（插件会为 payload-mcp-api-keys 表增加新列）

2. 配置 ~/.cursor/mcp.json

推荐使用 mcp-remote 桥接（避免 Cursor 直连远程 MCP 时的传输协商问题）。

推荐写法（已验证可用）：在 env 中写入 Key，args 里用 ${MCP_API_KEY} 供 mcp-remote 替换（不要用真实 Key 提交到 git）：

1{
2  "mcpServers": {
3    "crispy": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote",
8        "http://localhost:3333/api/mcp",
9        "--transport",
10        "http-first",
11        "--header",
12        "Authorization:Bearer ${MCP_API_KEY}"
13      ],
14      "env": {
15        "MCP_API_KEY": "你的MCP_API_KEY"
16      }
17    }
18  }
19}

• 本地：args 中 URL 为 http://localhost:3333/api/mcp
• 线上：改为 https://your-site.com/api/mcp，env.MCP_API_KEY 换成线上 Key

不推荐单独依赖 envFile + ${env:MCP_API_KEY}：在部分 Cursor 版本中变量可能未注入，导致 POST /api/mcp 401 或工具列表只有约 68 个（缺 Globals / 自定义 tools）。若必须用 envFile，请确认 MCP 日志里 Using custom headers 的 Bearer 后是完整 Key，而不是字面量 ${env:MCP_API_KEY}。

Key 轮换后：更新 env.MCP_API_KEY（或重新 pnpm cli mcp:key 后粘贴新值），完全退出 Cursor 再打开，并在 Settings → MCP 中 Reconnect。

3. 在 Cursor 中连接

• 打开 Settings → MCP，找到 crispy
• 点击 Reconnect，状态变绿即成功
• 正常应看到约 87 个工具：69 个 Collection（如 findPosts、createPages）+ 12 个 Global（如 findHeader、updateSiteSettings）+ 6 个自定义（如 semantic_search、purge_frontend_cache）
• 验证：MCP_API_KEY=xxx pnpm cli verify:phase1（本地）；或 curl POST 目标站 /api/mcp 测 initialize

日志里偶发 GET /api/mcp 401（无 Bearer）多为 mcp-remote OAuth 探测，可忽略；POST /api/mcp 200 即表示鉴权正常。

4. 怎么用：直接对话

连上后无需写脚本，在 Agent 对话里描述需求即可。Cursor 会自动调用 MCP 工具：

• 「查一下最近 5 篇 posts」→ findPosts
• 「语义搜索 Payload 相关文章」→ semantic_search
• 「读取站点 header 配置」→ findHeader
• 「清掉全部前台页面缓存」→ purge_frontend_cache
• 「新建一篇草稿，标题是…」→ createPosts
• 「给文章加标签 SSE，没有就创建」→ findTags / createTags / updatePosts

5. 可用工具范围

工具分三类（以当前默认 Key 全开为例，共 87 个）：

类别 | 数量 | 示例

Collection 自动生成 | 69 | findPosts、updatePages、createTags

Global 自动生成 | 12 | findHeader、updateSiteSettings、findCacheSettings

自定义（mcpPlugin.mcp.tools） | 6 | semantic_search、restore_document、purge_frontend_cache

权限在 Admin → MCP → API Keys 中按 Collection / Global / payload-mcp-tool 细粒度开关；未勾选的不会出现在 tools/list。

6. 与 Admin AI 助手的区别

• MCP：给 Cursor 等外部 Agent，JSON-RPC，Bearer Key；Globals 用 findXxx / updateXxx；Collection 用 find/create/update + 集合名
• Admin AI 助手：后台浮窗，SSE 对话，Cookie 鉴权；统一入口 get_global / update_global，另含对话会话等

二者能力已基本对齐（缓存、Globals、语义搜索、回收站恢复等），详见 /admin/dev-docs#mcp。

7. 常见问题

• 显示 Logout / 连接失败：确认站点在线、URL 正确；改用上文 env 块配置；Reconnect 或 Reload Window
• POST /api/mcp 401：Key 未传入 header；检查 env.MCP_API_KEY 与 mcp-remote 日志中的 Bearer
• 只有 68 个工具：多为 Key 权限未开 Globals / 自定义 tools，或 Cursor 用了旧缓存；在 Admin 勾选权限后 Reconnect；必要时删除 ~/.cursor/projects/<项目>/mcps/user-crispy/tools 缓存目录
• column "header_find" does not exist：PostgreSQL 未跑迁移；执行 pnpm cli db:migrate
• find 查询 where：须传 JSON 字符串，不是对象

8. 小结

配置 mcp.json（env 块 + mcp-remote）→ Reconnect → 确认约 87 个工具 → 直接对话操作 CMS。Key 轮换后记得更新 env 并重启 Cursor。更多细节见 /admin/dev-docs#mcp。