MCP 连接排错

大多数连接问题来自四处：A大侠服务未运行、地址填错、配置语法错误，或 Agent 没有重新发现工具。

先做 60 秒快速检查

1. 保持 A大侠打开：如果 A大侠已经退出，本地 MCP 服务没有启动，任何 Agent 都无法连接。
2. 打开健康检查地址：访问 http://127.0.0.1:48327/healthz，确认本地服务有响应。
3. 逐字核对 MCP URL：必须使用 http://127.0.0.1:48327/mcp，不要遗漏端口或 /mcp。
4. 重启 Agent：保存配置后完整退出并重新打开 Agent，让它重新读取服务器和工具列表。

问题一：服务没有启动

现象： 健康检查地址无法打开，Agent 报连接被拒绝或超时。

1. 确认 A大侠进程仍在运行。
2. 退出后重新启动 A大侠，等待主界面加载完成。
3. 再次访问健康检查地址。

http://127.0.0.1:48327/healthz

问题二：端口被占用

现象： A大侠启动 MCP 服务时报端口错误，或 48327 返回了不属于 A大侠的内容。

先退出可能占用该端口的旧版 A大侠或残留进程，再重新启动当前版本。不要自行把 Agent URL 改成随机端口，因为应用和接入文档约定使用固定端口 48327。

避免同时打开多个版本

旧版和新版 A大侠同时运行时，只有一个进程能监听固定端口。完整退出旧版本通常即可恢复。

问题三：JSON 或 TOML 语法错误

现象： 保存按钮不可用、客户端提示配置解析失败，或整个 MCP 列表都没有加载。

JSON / JSON5 检查

• 引号使用英文半角字符，不要使用中文弯引号。
• 键值之间保留冒号，多个字段之间保留逗号。
• 合并配置时不要出现两个同名顶层键。

TOML 检查

• Codex 区块标题应为 [mcp_servers.a_stock_mcp]。
• 字段使用等号，不使用 JSON 的冒号。
• 不要重复声明同名区块。

问题四：服务在线，但没有工具列表

现象： 健康检查正常，Agent 也显示服务器存在，但会话中看不到工具。

1. 确认连接地址末尾是 /mcp，而不是 /healthz。
2. 确认 transport 是 streamable-http（如果客户端要求显式填写）。
3. 保存配置后重启 Agent。
4. 在 Agent 的 MCP 管理界面或命令中刷新工具列表。
5. 新建会话再测试，旧会话可能仍保留配置前的上下文。

浏览器打开 /mcp 并不是连接测试

浏览器发送的是普通 GET 请求，而 MCP 客户端需要完成协议握手。请使用 Agent 自带的 MCP 状态页或工具列表判断是否连接成功。

仍然无法连接

记录以下信息后再反馈，能显著缩短排查时间：

• 操作系统与版本。
• A大侠版本、Agent 名称与版本。
• 健康检查是否响应。
• 脱敏后的配置片段。
• 完整错误提示和出现步骤。

不要在截图或配置中公开账户凭据、Token 或其他密钥。