VVCMS MCP 接入与使用教程

本文介绍 VVCMS 内置的 MCP（Model Context Protocol）服务如何开启、鉴权，以及如何在各类 AI Agent / 客户端中接入并使用它。读完你可以把 VVCMS 的栏目、内容、主题、文件与系统配置能力直接交给大模型客户端去调用。

一、VVCMS MCP 是什么

VVCMS 把后台的核心能力（栏目、内容、主题文件、文件上传、标签、关键词、留言审核、系统配置等）以 MCP 工具 的形式暴露给大模型客户端。任何支持 MCP 的 Agent 都可以通过标准协议连接 VVCMS，像调用函数一样查询或操作站点。

传输层：Streamable HTTP（无状态模式）。每个请求都会新建一个 Server 并重新注册工具，因此配置可以在后台热改、无需重启。
接入端点：/api/mcp
鉴权：HTTP Bearer Token，且调用者必须是管理员。
工具数量：当前共 71 个工具，覆盖内容、栏目、主题、文件、配置、标签、关键词、互动等场景。
审计：所有写操作都会写入事件日志（成功与失败都留痕），可在后台「系统 → 日志」中查看。

二、访问端点与鉴权

2.1 访问端点

假设你的站点地址为 https://your-domain.com，那么 MCP 的完整地址是：

https://your-domain.com/api/mcp

如果你的站点部署在子路径或带端口，请按实际地址拼接，路径固定为 /api/mcp。

2.2 鉴权方式（重点）

MCP 使用标准的 Authorization: Bearer 头，令牌就是后台个人中心「用户令牌」里显示的那串字符。服务端会根据令牌识别出对应的管理员账号。

Authorization: Bearer YOUR_ADMIN_TOKEN

需要特别区分，避免踩坑：

不是后台登录返回的 JWT（VToken）。后台网页登录用的是另一套鉴权，不能直接作为 MCP 的 Bearer 使用。
不是 XToken。外部 API 历史上用过 XToken，但 MCP 通道统一使用个人中心里的用户令牌。
令牌具有完整权限，务必只在 HTTPS、内网或网关白名单环境中暴露；不要写进脚本、日志、前端代码或公开仓库。

2.3 获取管理员令牌

令牌直接在后台个人中心 → 用户令牌里获取，无需任何技术操作：

以管理员身份登录后台。
进入个人中心，找到「用户令牌」卡片。
点击「复制」按钮，即可复制当前令牌。
把复制的令牌按 Bearer 你的令牌 的格式填进客户端的 Authorization 请求头。

如果令牌泄露或需要更换，点击「刷新」按钮即可重新生成一个新令牌（旧令牌立即失效，已连接的客户端需要同步更新）。

2.4 在后台开启 MCP

以管理员身份登录后台。
进入 AI → MCP 设置页。
打开「启用」开关并保存。
若你的客户端通过公网域名或反向代理访问，请同时打开「关闭本地回路保护」（见第六节）。

未开启时访问 /api/mcp 会得到 404 MCP service is disabled。

三、通用连接配置（所有客户端的共同基础）

无论用哪个 Agent，连接 VVCMS MCP 本质上只需要两样东西：

url：https://your-domain.com/api/mcp
headers.Authorization：Bearer YOUR_ADMIN_TOKEN

标准 MCP over Streamable HTTP 的配置形如：

{
  "mcpServers": {
    "vvcms": {
      "type": "streamableHttp",
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

不同客户端的字段名略有差异（有的用 transport，有的用 type），但都遵循「填 URL + 在请求头里带 Authorization」这一原则。下面给出常用客户端的写法。

四、在各 Agent / 客户端中的具体配置

4.1 WorkBuddy（当前环境）

在 WorkBuddy 中通过「自定义连接器（MCP）」添加即可：

打开连接器 / MCP 配置入口，新增一个自定义 MCP 服务器。
传输方式选择 Streamable HTTP（部分版本写作 HTTP / streamable）。
URL 填写 https://your-domain.com/api/mcp。
在「自定义请求头 / Headers」里新增一行：Authorization = Bearer YOUR_ADMIN_TOKEN。
保存后信任该服务器，即可在会话中调用 VVCMS 工具。

4.2 Claude Desktop

编辑 claude_desktop_config.json（macOS 位于 ~/Library/Application Support/Claude/）：

{
  "mcpServers": {
    "vvcms": {
      "type": "http",
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

如果你的 Claude Desktop 版本尚不支持原生 HTTP 类型，可先用 mcp-remote 做桥接：用 command 启动 npx mcp-remote 并把 URL 与 Authorization 头作为环境变量传入。新版 Claude Desktop 已原生支持 type: "http"。

4.3 Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "vvcms": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

保存后在 Cursor 的 MCP 面板刷新，看到 vvcms 工具列表即接入成功。

4.4 VS Code / GitHub Copilot

在 settings.json 的 mcp.servers 中增加：

{
  "mcp": {
    "servers": {
      "vvcms": {
        "type": "http",
        "url": "https://your-domain.com/api/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_ADMIN_TOKEN"
        }
      }
    }
  }
}

4.5 Cline

编辑 cline_mcp_settings.json（位于 VS Code 用户配置目录）：

{
  "mcpServers": {
    "vvcms": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

4.6 ChatGPT / OpenAI 桌面端

在桌面端的 MCP 设置里「Add a connector / custom server」，选择 HTTP / Streamable 类型，填写：

URL：https://your-domain.com/api/mcp
Header：Authorization: Bearer YOUR_ADMIN_TOKEN

保存后启用即可在对话中调用。

4.7 Cherry Studio / 通用 OpenAI Agents

大多数国产或第三方 MCP 客户端都提供「MCP 服务器 → 添加 → 类型选 Streamable HTTP / HTTP」，同样填 URL 与 Authorization 头即可。只要客户端支持 MCP over HTTP 并允许自定义请求头，就能接入 VVCMS。

五、工具范围与权限控制（只读 / 白名单）

VVCMS MCP 在服务端提供两层工具过滤，无需改动客户端：

只读模式（read_only）：开启后只注册读工具，所有写工具都不会暴露给模型。适合把 MCP 当作查询入口、不允许模型修改内容的部署形态。
工具白名单（enabled_tools）：填写允许注册的工具名数组，留空表示不限制。白名单会自动归一化（小写、去空格、去重），避免 List_Articles 这种大小写写法静默失效。

这两项在 MCP 的配置中设置（即 { "enabled": true, "read_only": true, "enabled_tools": ["list_articles","get_article"] } 这样的配置项）。注意 mcp 属于自管配置，不能通过通用 update_option 工具修改，需在后台或配置文件中调整。

六、安全与排错

6.1 本地回路保护 / DNS rebinding

MCP SDK 自带本地回路（DNS rebinding）防护：当服务监听在本机回环地址，而请求 Host 是外部域名时，会返回 403。这是为了挡住浏览器侧的 DNS rebinding 攻击。

如果你通过反向代理 + 公网域名访问，建议在 MCP 配置中关闭「本地回路保护」（后台开关 disable_localhost_protection）。
反向代理要正确透传 Host 与 X-Forwarded-Proto，服务端据此生成正确的资源元数据地址。

6.2 常见错误码

现象	原因	处理
`404 MCP service is disabled`	MCP 未启用	后台 AI → MCP 打开启用开关
`401 Unauthorized`	缺令牌或令牌无效	检查 Authorization 头与个人中心「用户令牌」是否一致
`403 Forbidden`	非管理员令牌，或本地回路防护拦截	换管理员令牌；公网/反代访问时关闭本地回路保护
`429`	来源 IP 连续鉴权失败过多被临时拉黑	等待解除，或检查令牌是否长期错误

6.3 安全建议

只在 HTTPS 或内网/网关白名单环境中暴露 /api/mcp。
令牌具有完整管理员权限，不要写进脚本、日志、前端代码或公开仓库；怀疑泄露时到个人中心点「刷新」换新令牌。
生产环境优先使用 read_only 或 enabled_tools 白名单收窄暴露面。
写操作均有审计日志，定期复核「系统 → 日志」。

七、当前可用工具清单（按类别）

以下为当前 71 个工具，按能力分组：

栏目

list_columns、get_column、create_column、update_column、delete_column、list_column_tree、sort_columns、update_column_page

内容 / 文章

list_articles、get_article、create_article、update_article、delete_article、batch_delete_articles、sort_articles、baidu_push_articles

主题文件

list_theme_directory、create_theme_file、edit_theme_file、delete_theme_file、create_theme_directory、delete_theme_directory、read_theme_file、rename_theme_path、copy_theme_path

文件

upload_file、list_files、delete_file、rename_file、remote_download_file

系统配置（通用）

list_options、get_option、update_option

关键词

list_keywords、get_keyword、create_keyword、update_keyword、delete_keyword、import_keywords、expand_keywords

互动 / 留言评论

list_interactions、get_interaction、update_interaction、delete_interaction

系统配置（专用，密钥以掩码返回）

get_email_config / update_email_config、get_notify_webhook_config / update_notify_webhook_config、get_llm_config / update_llm_config、get_llm_image_config / update_llm_image_config、get_security_config / update_security_config、get_log_config / update_log_config、get_cms_config / update_cms_config、get_translation_config / update_translation_config、get_email_interaction_notify_to / update_email_interaction_notify_to、test_email、test_notify_webhook

提示：含凭据的配置（email、llm、llm_image、notify_webhook、mcp）不会出现在 list_options 中，且通用 get_option / update_option 会拒绝原样读写，请改用上述专用 get_*_config / update_*_config 工具。

本教程基于 VVCMS 内置 MCP 服务整理，工具数量随版本更新可能变化，请以实际 list_tools 返回为准。