MCP连接失败怎么办?WordPress MCP插件常见报错排查

MCP 插件装好了却连不上,或者连上后一调用就报错——这类问题绝大多数出在配置和环境上,很少是插件本身坏了。下面按报错类型给出定位方法。

一、客户端完全看不到 MCP 服务器

先确认三件事:

  • 配置文件位置对不对。Claude Code 读项目根目录的 .mcp.json;放错目录等于没配。
  • JSON 格式合法。少个逗号、多个括号都会让整个配置静默失效。用编辑器的 JSON 校验看一眼。
  • 改完配置要重启客户端。多数客户端只在启动时加载 MCP 配置,热更新不生效。

二、报 401 / 403:鉴权失败

说明请求到达了服务器但没通过鉴权:

  • Token 复制时带了空格或换行——重新复制一次
  • 请求头格式必须是 Authorization: Bearer 你的令牌,Bearer 后面有一个空格
  • 生成 Token 的账号必须是管理员。MCP 插件的接口通常限定 manage_options 权限
  • Token 被重置过——后台重新生成后,旧 Token 立即失效

三、报 404:接口地址不对

每个插件的接口路径不同,不能互相套用:

  • 通用版:/wp-json/easy-mcp-ai/v1/mcp
  • 子比版:/wp-json/zibll-mcp/v1/mcp
  • 知更鸟版:/wp-json/begin-mcp/v1/mcp

如果路径没错还是 404,检查固定链接设置——WordPress 的 REST API 依赖重写规则,进后台「设置 → 固定链接」点一次保存即可刷新。另外确认站点没有插件或安全策略屏蔽了 /wp-json/。

四、报 400 且提示 schema 无效

典型报错形如:

API Error: 400 tools.47.custom.input_schema:
JSON schema is invalid. It must match JSON Schema draft 2020-12

这不是你配置错了,而是某个 MCP 服务端导出的工具定义不合规。因为工具列表要整体提交给模型服务,只要有一个工具的 schema 非法,整个会话的所有请求都会失败。

定位方法:把连接的 MCP 服务器逐个禁用,看去掉哪个之后恢复正常,问题就出在那个插件上,把版本升到最新即可。这类问题通常在插件更新中修复。

五、连上了但工具列表是空的

  • 主题不匹配:主题专用版插件会检测当前主题,主题不对时不注册工具
  • 依赖插件没装:比如 RIPRO 版是以 WordPress Abilities 形式提供能力的,必须同时安装通用版 Easy MCP 作为 MCP 服务端,单独装 RIPRO 版不会有接口
  • 插件没启用:上传了但忘记点启用,这种情况比想象中常见

六、HTTPS 与网络问题

MCP 客户端一般要求 HTTPS。如果站点是 HTTP,或者证书过期、证书链不完整,连接会直接失败。用浏览器打开接口地址看一眼,能正常返回 JSON(哪怕是报错 JSON)说明网络层是通的。

另外,部分 CDN 和安全防护会拦截 POST 到 /wp-json/ 的请求,或者对请求头做过滤。排查时可以临时关闭防护测试。

七、页面报 PHP 警告或致命错误

如果是通过 AI 改完配置后前台开始报错,注意这两类:

Undefined array key:主题读取某个字段时该键不存在。常见于批量写入时只传了部分字段,而主题代码无条件取下标。补上缺失的键(用不到的传空值)即可。

Cannot access offset of type string on string:某个主题选项本该是数组,实际却是空字符串。这通常是该设置页从未在后台保存过。进对应设置页点一次保存,让主题写入完整默认值。

排查顺序建议

  1. 浏览器直接打开接口地址,确认网络层通
  2. 检查配置文件格式与位置,重启客户端
  3. 核对接口路径与 Token
  4. 确认插件已启用、主题匹配、依赖插件齐全
  5. 还不行就逐个禁用其它 MCP 服务器,排除干扰

接入方法见 WordPress MCP插件安装与配置教程,各客户端的配置写法见 用 Cursor / Claude Code / Grok 连接 WordPress MCP。

© 版权声明
THE END
喜欢就支持一下吧
点赞7 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容