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

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

1. 前置条件

• Crispy 服务可访问：本地开发用 pnpm cli dev:dev（默认 http://localhost:3333）；也可指向已部署的线上站点（如 https://your-site.com），只要 POST /api/mcp 能连通即可

• 已获取 MCP API Key：本地可用 pnpm cli mcp:key 或 db:seed；线上在 Admin → MCP → API Keys 创建，并写入 .env 的 MCP_API_KEY

• Key 在 Admin → MCP → API Keys 中有效，并关联 editor 用户

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

推荐使用 mcp-remote 桥接（避免 Cursor 直连远程 MCP 时的传输协商问题）。将 url 换成你的目标站点：

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      "envFile": "/path/to/crispy/.env"
15    }
16  }
17}
18
19// 本地：http://localhost:3333/api/mcp
20// 线上：https://your-site.com/api/mcp
Copy

envFile 指向项目 .env，Key 轮换后无需改 mcp.json。连接线上时把 args 中的 URL 改为生产域名即可；也可用直连 url + headers 方式，详见 /admin/dev-docs#mcp。

3. 在 Cursor 中连接

• 打开 Settings → MCP，找到 crispy

• 点击 Reconnect，状态变绿即成功

• 应能看到 findPosts、createTags、updatePages 等工具

• 验证：MCP_API_KEY=xxx pnpm cli verify:phase1（本地）；线上可用 curl POST 目标站 /api/mcp 测 initialize

4. 怎么用：直接对话

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

• 「查一下最近 5 篇 posts」→ findPosts

• 「新建一篇草稿，标题是…」→ createPosts

• 「给文章加标签 SSE，没有就创建」→ findTags / createTags / updatePosts

• 「把这篇改成已发布」→ updatePosts（_status: published）

5. 可用工具范围

工具由 Payload 按 Collection 自动生成，命名规则为 find/create/update/delete + 集合名（如 findCategories）。默认开放 posts、pages、categories、tags、links、jobs、media 等，权限在 payload-mcp-api-keys 中按 Key 细粒度控制。

6. 与 Admin AI 助手的区别

• MCP：给 Cursor 等外部 Agent，JSON-RPC 协议，Bearer Key 鉴权

• Admin AI 助手：后台浮窗，SSE 对话，Cookie 鉴权，含缓存/审计等定制工具

7. 常见问题

• 显示 Logout / 连接失败：确认目标站点在线、URL 正确，Reconnect MCP，或改用 mcp-remote 配置

• 401 Unauthorized：MCP_API_KEY 无效或已轮换；本地重新 pnpm cli mcp:key，线上在 Admin 重新创建 Key

• find 查询 where 参数需传 JSON 字符串，不是对象

8. 小结

配置 mcp.json（本地或线上 URL）→ Reconnect → 直接对话操作 CMS。日常改内容、加分类标签不需要再写脚本；只有 CI 批量任务才考虑脚本。更多细节见 /admin/dev-docs#mcp。