自学教程

Codex MCP

Codex 教程

Codex MCP 服务器配置

MCP 服务器（MCP Server）是实现模型上下文协议的后端服务，负责向外暴露工具、资源、提示模板；Codex 通过 MCP 客户端连接服务端，完成工具调用与上下文读取。MCP 服务器配置主要分为项目本地配置、全局用户配置两大类，支持多服务同时注册、独立权限控制、传输协议切换。本文讲解配置文件结构、多服务编写、传输方式、权限沙箱、验证排错与企业管控。

一、配置文件基础说明

Codex 通过 mcp_servers 节点定义 MCP 服务，配置可写在两处：

  1. 项目级配置：.codex/config.toml，提交至 Git，团队全员共享，作用于当前仓库。
  2. 用户全局配置：~/.codex/config.toml（Linux/macOS）、%USERPROFILE%\.codex\config.toml（Windows），仅本机生效，适用于个人本地工具。

优先级：项目配置 > 用户全局配置。项目内定义的同名 MCP 服务会覆盖全局配置。

配置字段通用说明

每个 MCP 服务配置包含基础必填字段：

字段说明
nameMCP 服务唯一标识，用于命令行 / 斜杆命令引用
transport传输协议，支持 stdio / http / websocket
commandstdio 模式：启动服务的可执行程序路径
argsstdio 模式：启动命令参数数组
urlhttp / websocket 模式：服务访问地址
env环境变量，传递给 MCP 服务进程
sandbox_mode沙箱权限：read-only / workspace-write / danger-full-access
disabled布尔值，true 代表临时禁用该服务

二、stdio 模式配置（本地进程，最常用）

stdio 模式会由 Codex 直接拉起子进程，通过标准输入输出和 MCP 服务通信，适合本地开发工具、数据库客户端、本地脚本服务。

示例 .codex/config.toml

[mcp_servers.db]
name = "db"
transport = "stdio"
command = "npx"
args = ["@modelcontextprotocol/server-postgres", "postgresql://user:pass@127.0.0.1:5432/mydb"]
sandbox_mode = "read-only"
disabled = false

[mcp_servers.files]
name = "files"
transport = "stdio"
command = "python"
args = ["./.codex/mcp/file_server.py"]
env = {WORKSPACE_ROOT = "${workspace_path}"}
sandbox_mode = "workspace-write"

三、HTTP / WebSocket 远程服务配置

远程 MCP 服务独立部署在服务器或容器中，Codex 通过网络访问，适合企业内部共享 MCP 服务。

[mcp_servers.enterprise-api]
name = "enterprise-api"
transport = "http"
url = "[https://mcp.example.com/mcp](https://mcp.example.com/mcp)"
# 认证头，用于企业内部鉴权
headers = {Authorization = "Bearer ${MCP_TOKEN}"}
sandbox_mode = "read-only"
disabled = false

WebSocket 只需要修改 transport="websocket" 和对应 ws:// 或 wss:// URL。

环境变量引用：${VAR_NAME}，Codex 会自动读取本机环境变量，不要明文写入密钥。

四、多 MCP 服务共存配置

同一个配置文件可以同时注册多个 MCP Server，Codex 会并行建立连接，每个服务独立沙箱隔离。

# 多服务示例
[mcp_servers.git]
name = "git"
transport = "stdio"
command = "uvx"
args = ["mcp-server-git"]
sandbox_mode = "read-only"

[mcp_servers.redis]
name = "redis"
transport = "stdio"
command = "npx"
args = ["@modelcontextprotocol/server-redis"]
sandbox_mode = "read-only"

五、权限与安全配置

5.1 sandbox_mode 权限选项

  • read-only：仅读取资源，禁止修改文件、执行破坏性操作。推荐数据库、日志、文档查询类MCP。
  • workspace-write：允许读写项目目录文件，禁止高危系统命令。适用于代码生成、文件处理服务。
  • danger-full-access：完整系统权限，可执行任意命令。企业环境必须人工审批，生产环境谨慎使用。

5.2 企业级管控（requirements.toml）

管理员可在项目 .codex/requirements.toml 限制允许启用的 MCP 服务列表，阻止加载未授权外部MCP。

[security.mcp_allowlist]
allowed_servers = ["git", "db", "internal-api"]
block_unknown = true

当 block_unknown=true，任何不在白名单内的 MCP 服务会被拒绝加载。

六、MCP 服务管理命令

Codex 内置斜杆命令，用于查看、重载、测试配置，在桌面/IDE/CLI通用。

# 列出所有已加载MCP服务，查看启用状态
/mcp list查看指定服务详情、声明的工具列表
/mcp info db
重载MCP配置（修改config.toml后刷新，无需重启会话）
/mcp reload
测试连接，校验服务连通性
/mcp ping db
临时禁用某个MCP服务
/mcp disable db
/mcp enable db

七、配置校验、日志与排错

7.1 配置校验步骤

  1. 编写配置后执行 /mcp reload 重载。
  2. 使用 /mcp ping <server-name> 测试连通性。
  3. 查看服务暴露的工具列表，确认工具正常注册。

7.2 查看日志

# CLI模式查看MCP服务日志
codex mcp logs --server db

常见报错：

  1. 命令路径错误：command 路径不存在，可使用绝对路径。
  2. 环境变量缺失：密钥、连接串未配置。
  3. 协议版本不匹配：MCP服务协议版本与Codex不兼容。
  4. 沙箱权限拦截：MCP服务尝试执行超出 sandbox_mode 的操作。

八、最佳实践

  1. 优先使用 stdio 用于本地工具，远程业务系统使用 HTTP/WS。
  2. 数据库、日志查询类服务一律使用 read-only，最小权限原则。
  3. 密钥、token 不要硬编码到配置文件，使用环境变量 ${VAR_NAME}。
  4. 项目内 MCP 配置提交 Git，但密钥等敏感信息放入用户全局配置或环境变量。
  5. 企业项目开启 block_unknown=true，仅白名单内MCP服务可加载。
  6. 单项目不要一次性挂载过多MCP服务，避免上下文膨胀、token消耗过高。

九、常见问题

Q：修改 config.toml 之后需要重启 Codex 吗？
A：不需要，执行 /mcp reload 即可重新加载MCP服务配置。

Q：全局配置和项目配置冲突以哪个为准？
A：项目 .codex/config.toml 优先级更高，同名服务会覆盖全局。

Q：MCP服务能否在子代理中单独启用/禁用？
A：可以。子代理配置（.codex/agents/*.toml）中可以设置 mcp_allowlist，为子代理单独限定可访问的MCP服务。

Q：MCP服务进程会自动退出吗？
A：stdio模式由Codex管理生命周期，会话结束自动关闭进程；HTTP远程服务需要独立维护启停。

十、总结

Codex MCP 服务器配置以 config.toml 为核心，支持 stdio、HTTP、WebSocket 三种传输方式，可在项目级别或用户全局定义。每个MCP服务独立配置沙箱权限，企业可通过白名单限制外部服务接入。配合 /mcp 系列斜杆命令，可以快速查看、重载、测试服务。合理配置MCP服务，能够安全地为Codex、子代理、Agent Skills提供外部数据源与工具能力。

标签：

0 条笔记