连接 Codex 与其他客户端
MCP 让 Codex 等 Agent 使用你的 AsyncTest 项目知识。完成一次配置后，就能在客户端里直接查询；新增、修改和删除仍需逐次确认。
1. 在 Settings 获取连接信息
点击 AsyncTest 桌面端左下角的头像或昵称，打开 Settings → 知识库 MCP。检查服务状态为 已启用，且显示服务地址。展开 当前可访问项目，确认目标项目在列表中。
地址以你的 Settings 为准
公网和企业内部环境可能使用不同地址。不要直接照抄截图中的演示地址，也不要使用 AsyncTest 网页首页地址代替 MCP 服务地址。
2. 创建专属凭证，保存 Token
点击 创建凭证，填写一个容易辨认的名称，例如“Codex 工作电脑”，选择有效期和权限。
| 权限 | 什么时候需要 |
|---|---|
| 读取知识 | 查找、盘点和阅读知识 |
| 发起变更 | 新增、修改、删除；仍需逐次确认 |
| 读取审计 | 查看已有知识提交和回执 |
只查询时保留读取权限即可。建议按设备或客户端分别创建凭证，方便单独撤销。
创建成功后，点击 复制 Token，保存在自己的密码管理器或其他安全位置，再点击 我已保存。
Token 只显示一次
离开或刷新后不能再查看完整 Token。遗失时撤销旧凭证并重新创建，不要把 Token 发到聊天、截图或代码仓库中。
3. 复制安全配置，接入 Codex
在同一页面找到 客户端连接配置，选择 Codex config.toml，点击 复制安全配置。
把复制的内容合并到 ~/.codex/config.toml，保留原有配置。如果已经有同名服务段，更新该段，不要重复添加。
下面仅展示格式；服务名和地址以 Settings 生成的内容为准：
[mcp_servers.asynctest-knowledge]
url = "https://你的服务地址/mcp"
bearer_token_env_var = "ASYNCTEST_MCP_TOKEN"
default_tools_approval_mode = "writes"
tool_timeout_sec = 300安全配置不包含 Token。 ASYNCTEST_MCP_TOKEN 是环境变量名称，实际值要设为刚保存的 Token。使用 Codex CLI 时，可以在启动它的同一终端中设置；以下适用于 macOS 默认的 zsh，输入不会显示在屏幕上：
read -rs 'ASYNCTEST_MCP_TOKEN?粘贴 MCP Token 后按回车：'
export ASYNCTEST_MCP_TOKEN
printf '\n'
codex这个设置仅对当前终端及从它启动的程序生效。桌面客户端必须能从自己的启动环境读取该变量；在另一个终端执行 export，不会更新已经打开的桌面客户端。重新打开客户端并新建对话，再检查连接。
环境变量与直接写入 Token 有什么区别？
环境变量方式让配置只保存变量名称，完整 Token 单独保管。直接把 Token 写入客户端的 Authorization 配置，也会让配置文件本身包含秘密：复制、同步、备份时都可能带走它。优先使用 Settings 的安全模板；其他客户端是否支持环境变量替换，应以该客户端文档为准，不能把 ${ASYNCTEST_MCP_TOKEN} 原样作为真实 Token 发给服务器。
Codex 的配置文件位置、HTTP Token 配置及 writes 审批选项已按 OpenAI 官方 MCP 文档核对。客户端工具审批与知识库的变更确认是两个步骤，批准调用工具不代表已经保存知识。
4. 检查连接，先选项目
在 Codex CLI 中输入 /mcp，查看当前连接状态。在普通终端中也可以检查配置（服务名以实际模板为准）：
codex mcp get asynctest-knowledge检查结果中的 url、bearer_token_env_var 是否与 Settings 模板一致。这个命令和 codex mcp list 只检查已配置服务；真正能否访问，还需要一次实际查询。
新建对话，发送：
使用 AsyncTest 知识库 MCP，先列出我可以访问的项目名称和项目 ID，不要修改任何内容。
找到目标项目后，用返回的 ID 继续，例如：
使用刚才列表中我选定的项目 ID，查询订单取消规则，并标明知识来源。如果目标仍不明确，先让我选择。
MCP 不继承桌面的当前项目
桌面里切换了项目，不会替 MCP 选择项目。每次查询或录入都要明确目标；同名项目按返回的稳定项目 ID 区分，不要让 Agent 猜。
能访问哪些项目，以当前账号有效的项目成员关系和凭证权限为准。退出项目后，原 Token 不会保留该项目的权限。
5. 在客户端里录入或修改
明确指定项目 ID 和内容，建议让 Agent 先整理成清晰的 Markdown，保留原有事实，再提交变更预览。如果不希望改写，请明确说：“不要美化，按原文录入。”
知识库预览的是 Agent 最终提交的内容。核对项目、正文和范围后，再回复确认；确认后按这个版本保存，不想继续就取消。没有发起变更权限的凭证不能写入，Token 也不会绕过项目权限或确认步骤。
Claude Code 与其他客户端
Settings 也提供 Claude .mcp.json 和 通用配置。选择对应标签，复制模板；Claude Code 的项目配置合并到 .mcp.json，并确保启动进程能够读取 ASYNCTEST_MCP_TOKEN。环境变量写法见 Claude Code 官方 MCP 文档。
通用客户端选择 Streamable HTTP，填入服务地址，按客户端要求配置 Bearer Token。不要把 HTTP 服务配置成需要本机启动命令的服务。连接后同样先列项目，再按 ID 使用知识。
常见问题
| 现象 | 处理方法 |
|---|---|
| 显示未启用、配置不完整或没有地址 | 联系 AsyncTest 管理员确认此环境已启用 MCP，并配置正确的服务地址。 |
| 连接失败、超时 | 核对地址与网络；企业内部地址需要在可访问该服务的网络中使用。 |
| 鉴权失败、401 | 检查启动客户端的进程能否读取 Token，凭证是否到期或已撤销。不要使用网页登录 Token 代替 MCP Token。 |
| 能连接，但找不到项目或无法写入 | 核对账号、项目成员关系、项目 ID 和凭证权限。 |
| 知识查询提示服务暂不可用 | 联系管理员检查知识服务；这不表示项目没有知识，也不能当作查询成功。 |
| Token 忘记保存 | 撤销旧凭证，再创建新的；列表里的前缀不能用于连接。 |
| 预览被取消或失效 | 没有成功回执就不要当作已写入；重新读取当前内容并发起新的预览。 |
不用某台设备时，在 当前凭证 列表撤销对应凭证。到期后需要重新创建并更新客户端中的 Token；永久凭证不会自动过期，请在不再使用时撤销。