验证与排查

确认真的接通

配置命令成功只代表客户端保存了地址。重启客户端或新建会话后，让智能体实际调用一次 list_docs 或 search_docs，确认返回了页面列表或搜索结果。

客户端只有在重新启动或新建会话后才会加载新的 MCP 配置。

工具调用需要审批

Codex 显示“工具调用需要审批”时，在交互式会话中批准即可。

使用“永不请求审批”等无交互策略的会话会拦截远程 MCP 工具调用。确认只需要三个只读工具后，可以在 ~/.codex/config.toml 中限定并允许它们：

[mcp_servers.qnbot_docs]
url = "https://docs.qnbot.com/mcp"
enabled_tools = ["search_docs", "get_doc", "list_docs"]

[mcp_servers.qnbot_docs.tools.search_docs]
approval_mode = "approve"

[mcp_servers.qnbot_docs.tools.get_doc]
approval_mode = "approve"

[mcp_servers.qnbot_docs.tools.list_docs]
approval_mode = "approve"

如果之前已经配置过 [mcp_servers.qnbot_docs]，请直接使用上面的完整配置替换，不要在 config.toml 中保留两个同名的 [mcp_servers.qnbot_docs] 配置块。

连接失败或服务不可用

检查客户端所在网络能否访问 https://docs.qnbot.com/mcp。

浏览器直接打开 /mcp 可能返回下面的错误，这是预期行为：MCP 客户端使用协议请求，不能用普通的网页 GET 判断服务是否故障。

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Method not allowed."
  },
  "id": null
}

排查顺序

1. 确认客户端已重启，并且服务出现在客户端的 MCP 列表中。
2. 让智能体调用 list_docs：返回页面说明连接正常，权限问题通常出在工具审批上。
3. 调用能返回页面但仍拿不到内容时，让智能体按 markdownPath 调用 get_doc 核对全文，见可用工具。