MCP 本地连接被拒绝怎么办？

按健康检查、监听地址、调用方环境和访问令牌逐层定位 MaskPilot 本地 MCP 连接失败。

更新于 2026年8月24日

MaskPilot MCP 默认监听当前电脑的 127.0.0.1:38427，但已有配置可能使用其他端口。始终以客户端 MCP 页面显示的「本机连接地址」为准。看到 connection refused 时，通常表示调用方没有连到这个本地监听端口；访问令牌错误则会返回未授权响应，两者需要分开排查。

第一步：检查本地服务是否存在

先从 MaskPilot MCP 页面复制实际连接地址，把末尾的 /mcp 临时改为 /health，再在同一台电脑上打开。默认地址示例：

http://127.0.0.1:38427/health

正常响应应包含 ok: true 和服务名称。健康检查不可用时，依次确认：

MaskPilot 客户端已经启动。
设置中的 MCP 已开启。
开启 MCP 时没有出现端口占用提示。
健康检查使用的是客户端当前显示的端口，而不是固定套用默认端口。
本机安全软件没有阻止 MaskPilot 监听回环地址。

健康检查只证明本地服务正在运行，不代表客户端已经登录，也不代表当前账号拥有工具调用权限。

第二步：确认调用方所在环境

MCP 地址必须完整复制客户端页面显示的值。默认示例为：

http://127.0.0.1:38427/mcp

调用方应与 MaskPilot 运行在同一台电脑、同一个可访问 Windows 回环网络的环境中。WSL、容器、远程开发机或严格网络沙箱里的 127.0.0.1 可能指向它们自己的网络空间，而不是 Windows 上的 MaskPilot。

不要把地址改成局域网 IP，也不要把本地端口转发到公网。MaskPilot 的本地 MCP 不监听 0.0.0.0，也不作为远程服务使用。

第三步：区分 HTTP 响应

连接被拒绝：本地端口没有可访问的监听服务，优先检查客户端、MCP 开关和调用方环境。
404：请求路径错误；确认结尾是 /mcp。
401：服务已经连通，但 Bearer Token 缺失或不匹配。直接在浏览器地址栏打开 /mcp 会发送不带令牌的 GET，因此也会先得到 401，不能作为 MCP 调用测试。继续查看无效令牌排查。
405：带有正确 Bearer Token 的请求使用了非 POST 方法。
JSON-RPC 错误：HTTP 已经连通。除方法名、参数和账号权限外，还要检查调用方与服务端是否支持同一 MCP 协议版本。

第四步：重新加载调用方配置

如果健康检查正常但 AI 工具仍显示离线：

核对配置中的 URL 是否完整且没有多余空格。
确认 Bearer Token 环境变量名与配置一致。
如果刚设置或重置令牌，完全退出并重新打开 AI 工具或其终端。
查看调用方的 MCP 日志，确认它实际请求的主机、端口和路径。
回到 MaskPilot 查看最近调用记录；没有记录通常表示请求尚未到达或未进入工具调用阶段。

使用 Codex 时，可对照本地 MCP 连接指南重新生成配置。不要把访问令牌直接写进可提交的配置文件，也不要在截图或日志中公开它。

第五步：检查协议版本兼容性

当前 MaskPilot 客户端声明 MCP 2025-06-18，使用基于 initialize 的连接流程。调用方需要支持这一版本，或具备从新版 MCP 流程回退到旧版初始化流程的兼容能力。

如果健康检查正常，但日志出现 server/discover、Unsupported protocol version、method not found 或错误码 -32601，可能是调用方只尝试新版协议，而不是端口或令牌错误。此时：

检查调用方是否仍支持 2025-06-18 或旧版初始化回退。
将 MaskPilot 与调用方更新到彼此兼容的版本。
不要自行伪造协议头或改写请求来绕过协商。
仍失败时，记录双方版本、原始错误和调用方日志，再联系支持。

MCP 官方的版本兼容性矩阵明确区分新版逐请求协议与旧版初始化协议；只有支持双向兼容的调用方才能自动连接旧版服务。

连接成功但工具仍失败

连接建立后，工具调用仍要求 MaskPilot 客户端保持登录，并受当前账号和成员权限限制。此时应保留原始错误提示，再查看AI 助手权限与令牌，不要把权限拒绝当作网络故障。