Codex MCP 接入教程
MCP 让 Codex 连接外部工具和数据系统，例如文档搜索、项目服务或团队工具。它扩大了 Codex 能访问的范围，也扩大了误调用和凭证泄露的影响。接入时先确认服务器、传输方式、认证和工具权限，再让模型使用。
查看当前配置
codex mcp list
codex mcp list --json先查看当前已有服务器，避免重复添加同名条目。需要检查单个服务器时：
codex mcp get SERVER_NAME --jsonJSON 输出适合保存诊断信息，但其中可能包含地址、环境变量名或权限范围，分享前应脱敏。
添加服务器
本地 stdio 服务器通常通过命令启动，远程服务器使用 URL。官方命令参考提供两种形式：
codex mcp add local-tools -- command --arg value
codex mcp add remote-docs --url https://example.com/mcp真实命令和 URL 要以服务器提供方文档为准。需要环境变量时使用服务器支持的注入方式，不要把真实 Token 写进仓库、截图或 shell 历史。添加后重新列出配置，确认名称、传输方式和地址。
OAuth 和认证
支持 OAuth 的远程服务器可以使用：
codex mcp login SERVER_NAME认证完成后，用 codex mcp list 或会话内 /mcp 查看服务器是否可见。认证成功只表示凭证流程完成，仍需确认工具列表、账号权限和实际请求能否返回。
第一次测试怎么做
先使用只读工具。让 Codex 列出工具名称并说明用途，再调用一个最小查询。不要一上来连接生产数据库、发消息或执行批量写入。测试时记录服务器响应、错误码、调用参数和是否产生外部副作用。
如果工具没有出现，先检查配置是否被当前 profile 覆盖、客户端是否重启、服务器进程是否能独立启动。若工具出现但调用失败，区分认证、网络、参数和后端业务错误。不要通过给所有工具开放权限来掩盖一个参数问题。
删除和恢复
codex mcp remove SERVER_NAME删除前保存必要的配置说明，不保存真实凭证。恢复时重新按官方文档添加，并从只读检查开始。MCP 配置与 CLI、IDE 或桌面端可能共享；修改后检查每个入口读取的是哪一份配置。
与 AGENTS.md 和权限的关系
AGENTS.md 可以说明什么时候使用某个 MCP、哪些数据不能发送，但它不能替代服务器权限。沙箱和审批策略也不会自动限制远程系统里的写入结果。三层都要设置：项目规则、Codex 运行权限、MCP 服务器自身权限。
完整工作流见Codex使用教程，报错分类见Codex 报错大全。
先理解模型、客户端和服务器各自做什么
模型决定需要什么信息，Codex 客户端把请求发送给相应工具，MCP 服务器再与文档、仓库或其他系统交互。排查时必须区分这几层：模型没有选择工具、客户端没有连接服务器、服务器拒绝认证，以及后端查询本身失败，处理方式都不同。
MCP 也不等于给模型添加新知识后永远记住。一次检索返回的是这次任务的上下文；连接方式、查询权限和数据更新时间仍由服务端决定。如果你要查询当前项目状态，应看工具返回的数据来源和时间，不要把模型已有的知识当作实时查询结果。
本地服务器怎样准备
本地 stdio 方式通常需要一个可执行命令及参数。先在普通终端单独启动它，确认依赖存在、运行时正确、凭证能读取，再交给 Codex 启动。如果服务器依赖 Node 或 Python，GUI 与终端拿到的 PATH 不一致时，可能出现“终端可运行、客户端找不到”。
服务端必须遵守自己的通信协议。日志写错输出通道、启动时等待人工输入、依赖安装失败，都可能让客户端以为连接超时。不要只反复延长超时，应查看服务器日志，确认它确实进入可处理请求的状态。具体要求以该服务器的官方资料为准。
添加命令中的 -- 用来分隔 Codex 参数和服务器启动命令。带空格的路径、脚本参数和不同 shell 的引用规则都要核对。先使用无歧义的测试路径验证，再迁移到正式项目，避免把路径解析错误误认为认证问题。
远程 HTTP 服务器怎样检查
远程连接先核对完整 URL，包括域名、路径和传输方式。能在浏览器打开首页，不代表那就是 MCP 端点；控制台、API 和 MCP 服务可能采用不同路径。优先使用服务商提供的正式 MCP 地址，不要根据产品域名自行拼接。
如果服务需要认证，先确认是 OAuth、Bearer Token 还是其他机制，再按当前客户端支持的方式配置。不要把 API Key 填入不对应的 OAuth 登录页，也不要把访问网页登录后的 Cookie 当作长期工具凭证。凭证适用的组织、项目和权限范围都应能够说明。
部分组织会统一下发服务器或禁止自行添加。遇到策略提示时，查看组织配置，而不是换一个名称重复创建同一连接。服务被发现但工具受限，也可能是账户没有相关权限，需要分别检查客户端和后端的授权范围。
让工具调用留下可审查结果
第一次验收可以要求：列出可用工具，选择一个只读查询，说明准备读取的对象，再返回结果和来源。不要使用包含真实用户数据的大查询作为连通性测试。选一个公开文档或测试项目，便于你检查返回内容是否准确。
验收记录应包含服务器名称、工具名称、输入概要、返回状态以及是否发生写入。日志应保留排错所需字段，但遮盖 Token 和敏感数据。截图往往只能说明某一时刻界面出现了文字，结构化响应和具体调用记录更有助于定位失败。
同名工具也可能来自不同服务器。在提示词中明确服务器和对象，有助于减少歧义；必要时先禁用无关连接。不要一次加入十几个相似服务，再让模型自己决定哪个是团队正式数据源。
从只读扩展到写入
只读验收通过后，若业务确实需要创建工单、编辑文档或发送消息，再逐项评估写入权限。使用测试空间，给出明确对象与预期变更，并检查执行后实际状态。写入成功但客户端断线时，不能直接重放，先查询是否已经产生结果。
对有副作用的工具，任务里应定义重试条件。读取失败通常可以重新查询，重复发送通知或重复创建记录却可能造成业务问题。MCP 本身并不替所有后端提供相同的撤销和幂等机制，需要按具体工具确认。
工具描述只是客户端看到的说明，不能替代服务端授权。即使项目规则写着“只允许读”，后端 Token 仍拥有全量写权限时，风险并没有被完全隔离。尽可能在服务端采用符合任务的权限，再让客户端和项目说明补充使用边界。
排查连接和认证失败
先用 codex mcp get 检查当前条目，再看 list 中是否能发现它。名称不存在，查配置来源；进程无法启动，查命令和运行时；连接超时，查网络和服务状态；401 查凭证；403 查范围；业务错误则看工具参数和返回原因。
如果 OAuth 登录完成后仍失败，核对登录的账号和组织是否正确，以及权限是否包含所需资源。不要把再次登录当作所有错误的解决办法。记录失败时间和请求标识，必要时由服务维护者对照服务器日志，通常比客户端反复重装更有用。
配置修改后确认当前会话是否重载。CLI、桌面端和 IDE 可能以不同进程运行，每个入口都应完成最小验收。如果一个入口正常、另一个入口异常，比较配置路径、环境和认证存储，而不是先判断服务整体故障。
MCP 与 ClawSocket 怎样配合
ClawSocket用于模型接入，MCP 用于连接工具和数据。两者是不同请求链。你可以先按第三方模型配置验证模型调用，再增加只读 MCP，最后测试模型能否正确选择工具并处理结果。
如果官方模型能调用某个工具，而第三方路径失败，应保留相同任务和工具输入，对照协议、模型能力和事件结果。不要仅凭“文本回复正常”就把问题归因于 MCP。模型服务对工具格式、并行调用和后续回合的支持，需要在实际组合中验收。
团队文档和维护
为每个正式连接记录负责人、服务地址、认证方式、允许对象、读写范围和已验收能力。不要在文档保存 Token 值。成员离职、组织权限调整或服务域名变化时，根据记录轮换或撤销访问，再做最小查询复测。
升级服务器或客户端前，保留可回退的配置说明，复测你真正使用的工具。不要为了追求“工具越多越好”而保留长期不用的连接。连接越多，任务描述越需要清楚；删掉无用条目也能减少误选和维护成本。
要把团队的使用边界写进项目，请参考AGENTS.md；要限制本地命令和文件访问，请看权限与沙箱。它们与服务器授权共同决定完整边界，任何一层都不能代替另外两层。
按能力而非工具数量验收
一个正式连接至少需要知道能发现哪些工具、能访问哪些对象、读操作如何验证、写操作能否撤销，以及凭证失效后有什么表现。把这些问题逐项记录，比只保存一张“连接成功”截图更能帮助团队维护。工具列表增加后，也应检查新增工具是否带来额外写权限。
如果服务端更新工具参数，客户端可能仍能连接，却在调用时返回错误。因此连接状态和业务调用状态需要分开监测。挑选团队经常使用的一条只读查询作为检查入口，失败时先保留响应，再判断是参数变化、数据权限还是服务异常。
移除工具后，不要忘记检查相关项目规则、自动化脚本和成员文档。它们可能仍要求调用已删除服务器，造成任务反复尝试。移除连接与撤销服务端凭证也不是同一件事，按实际使用范围决定是否还要在账户侧撤销。
MCP 接入涉及具体服务，不能从一个服务器的成功推断另一个也兼容。逐个记录来源和验收结果，保持每条连接的用途清楚，就能在后续扩展时保留可解释的边界。
接入完成后从哪里继续
连接能用之后，选择一个真实但范围小的任务，明确工具需要返回哪些信息，并检查这些信息是否真正影响了代码决策。外部上下文应该服务当前任务，而不应变成每轮都执行的大规模检索。若没有需要调用的场景，保持连接关闭也可以减少维护负担。
官方资料与核对范围
以下资料用于核对产品入口、命令和配置；练习与任务模板是本文提供的操作建议，不代表已在读者设备上运行。官方源码主分支会更新，安装时请再核对本机版本。