作者:互联网 时间: 2026-09-02 17:47:56
MCP(Model Context Protocol,模型上下文协议)允许 Codex 与外部工具和服务集成。
本节详细介绍如何配置和使用 MCP 服务器。
MCP 是一个开放协议,允许 AI 模型与外部工具和服务进行标准化交互。通过 MCP 服务器,你可以扩展 Codex 的能力:
MCP 基于开放的 Model Context Protocol 构建,支持跨不同工具的标准化集成。
通过设置菜单可以管理或添加 MCP 服务:

连接至自定义 MCP:

MCP 服务器在 ~/.codex/config.toml 的 mcp_servers 部分配置。
[mcp_servers.filesystem]# 服务器启动命令
command = "npx"
# 传递给命令的参数
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
# 服务器工作目录
cwd = "/path/to/workdir"
# 传递环境变量
env = {
NODE_ENV = "production"
}
[mcp_servers.docs]# MCP HTTP 服务器端点
url = "https://docs.example.com/mcp"
# 包含的 HTTP 头
http_headers = {
Authorization = "Bearer token"
}
你可以限制 MCP 服务器暴露的工具:
[mcp_servers.filesystem]# 允许的工具列表
enabled_tools = ["read_file", "write_file", "list_directory"]
# 拒绝的工具列表(在 enabled_tools 之后应用)
disabled_tools = ["delete_file"]
使用工具限制可以提高安全性,只暴露你需要的工具。
[mcp_servers.slow_server]command = "python"
args = ["-m", "slow_server"]
# 启动超时(秒,默认 10)
startup_timeout_sec = 30
# 每个工具调用超时(秒,默认 60)
tool_timeout_sec = 120
[mcp_servers.protected]url = "https://api.example.com/mcp"
# 请求的 OAuth 范围
scopes = ["read", "write"]
# OAuth 资源参数
oauth_resource = "codex-integration"
# Bearer token 环境变量
bearer_token_env_var = "EXAMPLE_API_TOKEN"
[mcp_servers.api]url = "https://api.example.com/mcp"
# 从环境变量填充 HTTP 头
env_http_headers = {
X_API_KEY = "MY_API_KEY"
}
# 静态 HTTP 头
http_headers = {
X_Custom_Header = "value"
}
# 固定回调端口mcp_oauth_callback_port = 8080
# 自定义回调 URL
mcp_oauth_callback_url = "https://my-devbox.example.com/callback"
# 凭证存储位置
mcp_oauth_credentials_store = "keyring" # file | keyring | auto
你可以为每个 MCP 服务器的工具单独设置权限:
[mcp_servers.docs.tools.search]# 权限模式:ask | approve | deny
approval_mode = "approve"
| 权限模式 | 说明 |
|---|---|
ask | 每次执行前询问(默认) |
approve | 自动批准 |
deny | 自动拒绝 |
配置工具权限时要小心,确保只授予你信任的工具自动批准权限。
[mcp_servers.filesystem]command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
[mcp_servers.github]command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = {
GITHUB_PERSONAL_ACCESS_TOKEN = "your-token-here"
}
[mcp_servers.postgres]command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
你可以通过 npm 安装更多 MCP 服务器:
# 搜索 MCP 服务器npm search @modelcontextprotocol/server# 安装 MCP 服务器npm install -g @modelcontextprotocol/server-filesystem
OpenAI 官方提供了多种 MCP 服务器,查看 GitHub 仓库 获取完整列表。
检查以下内容:
增加超时时间:
tool_timeout_sec = 120
确保 OAuth 回调端口未被占用,凭证存储配置正确。
使用 codex --verbose 可以查看详细的 MCP 调试信息。检查命令是否正确安装,尝试手动运行命令确认没有错误。
在配置文件的 mcp_servers.<id>.tools.<tool> 部分配置。
在配置中添加 enabled = false 或直接删除配置。
没有严格限制,但建议只配置你实际需要的服务器。