Codex 集成

本指南介绍如何将 1MCP 与 Codex 集成，实现高级 MCP 服务器管理、项目特定配置和可流式传输的 HTTP 传输能力。

概述

Codex 版本兼容性

Codex < 0.44.0（有限支持）

0.44.0 之前的 Codex 版本对 MCP 服务器的支持有限：

无 HTTP 传输：无法直接连接到 HTTP/SSE 端点
仅支持 STDIO：仅支持通过 STDIO 传输的 MCP 服务器
无项目特定设置：仅全局配置，没有项目特定的服务器管理

Codex ≥ 0.44.0（HTTP 传输支持）

Codex 0.44.0 及更高版本原生支持基于 HTTP 的 MCP 服务器：

HTTP 传输：可直接连接到 HTTP/SSE 端点
全局配置：HTTP 服务器在 config.toml 中全局配置
无项目特定设置：仍然缺乏项目特定的服务器管理

注意：Codex 项目特定配置尚未实现（参见 codex pr#4007）。

为什么即使在 Codex ≥ 0.44.0 时仍推荐使用 1MCP 代理？

虽然 Codex ≥ 0.44.0 可以直接连接 HTTP MCP 服务器，但仍然推荐使用 1MCP 代理，原因如下：

1. 项目特定服务器管理

toml

# 直接 Codex HTTP（全局 - 影响所有项目）
[mcp_servers.1mcp]
url="http://localhost:3050/mcp"

# vs 1MCP 代理（通过 .1mcprc 实现项目特定）
# 项目 A：{"preset": "web-dev"}      # 仅 Web 服务器
# 项目 B：{"preset": "data-science"} # 仅数据服务器
# 项目 C：{"preset": "backend"}     # 仅后端服务器

2. 高级标签过滤

bash

# 1MCP 代理：通过预设选择性暴露服务器
npx -y @1mcp/agent preset create web-dev --filter "frontend OR design"
npx -y @1mcp/agent preset create data-science --filter "data-science OR ai"
npx -y @1mcp/agent preset create backend --filter "backend OR api"

3. 集中式服务器管理

单一源：在一个地方管理所有 MCP 服务器
热重载：无需重启 Codex 即可更新配置
团队共享：在团队成员之间共享预设

1MCP 桥接解决方案

1MCP 通过以下方式提供全面的 MCP 服务器管理：

HTTP ↔ STDIO 代理：在 HTTP 传输和 STDIO 传输之间转换
项目级配置：通过 .1mcprc 文件和预设实现项目级 MCP 服务器设置
高级过滤：基于标签的服务器选择和过滤
集中式管理：统一的服务器生命周期和能力聚合

.1mcprc 与预设 + 代理 + 服务组合为不同的项目提供不同的 MCP 服务器，即使支持 HTTP 传输的更新版 Codex 也能实现此功能。

术语

为避免混淆，本指南使用以下术语：

术语	定义	示例命令
1MCP Agent	包含所有 1MCP 功能的整个 npm 包 `@1mcp/agent`	`npx -y @1mcp/agent --version`
1MCP Server	使用 `serve` 命令启动的聚合 MCP 服务器的 HTTP 服务器进程	`npx -y @1mcp/agent serve`
1MCP Proxy	使用 `proxy` 命令启动的用于 Codex 集成的 STDIO 到 HTTP 桥接	`npx -y @1mcp/agent proxy`
MCP Server	个别的模型上下文协议服务器（filesystem、github 等）	`npx @modelcontextprotocol/server-filesystem`
Preset	通过标签过滤定义要暴露的 MCP 服务器的命名配置	`npx -y @1mcp/agent preset create my-preset`

架构流程：

Codex (STDIO) ← 1MCP Proxy (STDIO↔HTTP) ← 1MCP Server (HTTP) ← MCP Servers

备选方案：直接 HTTP 传输（Codex ≥ 0.44.0）

对于更简单的设置，将 Codex 直接连接到 1MCP Server 通过 HTTP：

bash

1mcp serve  # 启动 1MCP 服务器

编辑 config.toml：

toml

[mcp_servers.1mcp]
url = "http://localhost:3051/mcp"

限制：所有服务器全局可用（无项目特定过滤，无基于标签的选择）。使用 1MCP 代理进行项目特定服务器管理和团队协作。

前置条件

系统要求

Node.js：MCP 服务器和 1MCP agent 需要 18+ 版本
bash
```
node --version  # 应该是 v18.0.0 或更高
```
1

1MCP Agent：推荐最新版本

bash

# 全局安装以便使用（推荐）
npm install -g @1mcp/agent

# 验证安装
1mcp --version

# 备选方案：使用 npx（无需安装）
npx -y @1mcp/agent --version

提示：使用 npm install -g @1mcp/agent 全局安装允许你在本指南中使用更短的 1mcp 命令而不是 npx -y @1mcp/agent。

安装

如果你还没有安装 Codex，请访问官方 Codex 仓库获取安装说明。

配置文件位置

Codex 将其配置存储在：

Linux/macOS：~/.codex/config.toml
Windows：%APPDATA%\\codex\\config.toml

如果目录不存在则创建：

bash

mkdir -p ~/.codex  # Linux/macOS

已知问题

⚠️ 重要：Codex 0.44.0 的 HTTP 传输支持是实验性的。如果直接 HTTP 连接遇到问题，请改用 1MCP 代理方法。详情请参见故障排除。

验证清单

在继续之前，请验证：

[ ] 已安装 Codex 版本 ≥ 0.44.0（或代理方法的任何版本）
[ ] 已安装 Node.js 版本 ≥ 18
[ ] 可以成功运行 1mcp --version（或 npx -y @1mcp/agent --version）
[ ] 配置目录存在于 ~/.codex/
[ ] 有一个用于测试的工作目录（例如 ~/test-codex-integration/）

项目目录

你需要一个工作空间目录来使用集成。这里是你将创建 .1mcprc 配置文件的地方。

快速开始

1. 安装并启动 1MCP 服务器

bash

# 添加一些带有标签的 MCP 服务器用于预设过滤
1mcp mcp add filesystem --tags=files,local -- npx -y @modelcontextprotocol/server-filesystem /tmp
1mcp mcp add github --tags=git,remote,collaboration -- npx -y @modelcontextprotocol/server-github

# 在后台启动 1MCP 服务器
1mcp serve

注意：如果你没有全局安装，请使用 npx -y @1mcp/agent 代替 1mcp

2. 创建项目配置

在你的 Codex 项目目录中，创建一个 .1mcprc 文件：

json

{
  "preset": "codex-development"
}

3. 创建预设

bash

# 使用标签为 Codex 开发创建预设
1mcp preset create codex-development --filter "files OR git OR collaboration"

重要：预设基于标签过滤服务器。始终标记你的服务器，否则它们不会被包含在预设中。

4. 配置 Codex

在你的 Codex 配置中添加 1MCP 代理作为 MCP 服务器：

编辑你的 Codex config.toml 文件（位置见前置条件）：

toml

[mcp_servers.1mcp]
command = "npx"
args = ["-y", "@1mcp/agent@latest", "proxy"]

重要：
1MCP 代理的工作目录应该是包含 .1mcprc 的项目目录
从你的项目根目录启动 Codex 以确保它加载正确的配置

5. 在你的项目目录中启动 Codex

bash

cd /path/to/my-project
codex

6. 在 Codex 中测试

bash

# 在 Codex 中测试
/mcp

架构

1MCP 代理集成（推荐）

┌─────────────────┐     STDIO      ┌──────────────────┐      HTTP      ┌─────────────────┐
│      Codex      │ ◄────────────► │    1MCP Proxy    │ ◄────────────► │   1MCP Server   │
│   (any version) │                │   (reads .1mcprc)│                │   (no auth)     │
└─────────────────┘                └──────────────────┘                └─────────────────┘
        │                                   │                                   │
        │                                   │                                   ▼
        │                                   │                          ┌─────────────────┐
        │                                   │                          │   MCP Servers   │
        ▼                                   ▼                          │ (filesystem,    │
┌─────────────────┐                ┌──────────────────┐                │  github, db,    │
│ config.toml     │                │ .1mcprc + Preset │                │  etc.)          │
│(MCP server list)│                │ (project config) │                └─────────────────┘
└─────────────────┘                └──────────────────┘                         │
                                                                          Tag-based
                                                                         filtering

数据流：

Codex 配置：在 config.toml 中添加 1MCP 代理作为 MCP 服务器
项目检测：代理从当前项目目录读取 .1mcprc 文件
预设加载：代理加载指定的预设配置
服务器连接：代理通过 HTTP 连接到 1MCP 服务器
标签过滤：1MCP 服务器基于预设标签过滤 MCP 服务器
能力聚合：过滤后的服务器暴露给 Codex
双向通信：MCP 协议通过代理桥接流动

直接 HTTP 集成（Codex ≥ 0.44.0）

┌─────────────────┐     HTTP/SSE   ┌──────────────────┐
│      Codex      │ ◄────────────► │   1MCP Server    │
│   (≥ 0.44.0)    │                │   (global config)│
└─────────────────┘                └──────────────────┘
        │                                   │
        ▼                                   ▼
┌─────────────────┐                ┌─────────────────┐
│ config.toml     │                │   MCP Servers   │
│ (HTTP URL only) │                │ (all servers,   │
└─────────────────┘                │  no filtering)  │
                                   └─────────────────┘

限制：无项目特定配置，无标签过滤，仅全局服务器

关键差异

方面	1MCP 代理	直接 HTTP
项目特定配置	✅ `.1mcprc` 文件	❌ 仅全局
服务器过滤	✅ 基于标签的预设	❌ 所有服务器
项目隔离	✅ 不同项目使用不同服务器	❌ 所有地方使用相同服务器
团队共享	✅ 可共享的预设	❌ 手动同步
设置复杂性	⚠️ 中等	✅ 简单

工作目录要求

关键：必须从包含 .1mcprc 文件的项目目录执行 1MCP 代理：

bash

# ✅ 正确 - 从项目根目录
cd /path/to/my-project
codex

# ❌ 错误 - 从错误的目录
cd /home/user
codex  # 不会找到 .1mcprc

如果使用 Codex 的配置文件方法，请确保在 MCP 服务器配置或工作空间设置中正确设置工作目录。

配置选项

基本项目配置

在你的项目根目录创建 .1mcprc：

json

{
  "preset": "development-setup"
}

带过滤的高级配置

json

{
  "filter": "web OR api OR filesystem"
}

多环境设置

为不同环境创建不同的预设：

开发（.1mcprc.dev）：

json

{
  "preset": "dev-environment",
  "filter": "filesystem,web,database,test"
}

生产（.1mcprc.prod）：

json

{
  "preset": "production",
  "filter": "web,api,database,monitoring"
}

在环境之间切换：

bash

# 使用开发预设
ln -sf .1mcprc.dev .1mcprc

# 使用生产预设
ln -sf .1mcprc.prod .1mcprc

预设管理

创建预设

bash

# Web 开发预设
npx -y @1mcp/agent preset create web-dev --filter "filesystem,web,api"

# 数据科学预设
npx -y @1mcp/agent preset create data-science --filter "filesystem,database,python"

# 全栈预设
npx -y @1mcp/agent preset create full-stack --filter "web,api,database,filesystem"

列出预设

bash

npx -y @1mcp/agent preset list

在项目中使用预设

你的 .1mcprc 文件仅引用预设：

json

{
  "preset": "web-dev"
}

这能够实现：

团队一致性：在团队成员之间共享预设
轻松切换：通过更新预设名称更改环境
集中式管理：在一个地方更新服务器

示例：项目特定预设

bash

# Web 开发
1mcp mcp add filesystem --tags=files,web -- npx -y @modelcontextprotocol/server-filesystem ./src
1mcp preset create web-dev --filter "files OR git OR web"
echo '{"preset": "web-dev"}' > .1mcprc

# 数据科学
1mcp mcp add python --tags=python,data -- npx -y @modelcontextprotocol/server-python
1mcp preset create data-science --filter "python OR database OR data"
echo '{"preset": "data-science"}' > .1mcprc

# 团队协作 - 不同角色使用不同预设
1mcp preset create frontend --filter "frontend OR ui OR design"
1mcp preset create backend --filter "backend OR database OR api"

标签和预设：基本概念

标签为何重要

标签是 1MCP 过滤系统的基础。它们能够实现：

项目特定服务器：不同项目访问不同的 MCP 服务器
团队协作：共享定义团队所需服务器的预设
灵活分组：按功能、环境或团队对服务器进行分组
安全性：使用基于标签的过滤限制对敏感服务器的访问

关键原则：预设基于标签过滤 MCP 服务器，而不是服务器名称。

标签策略

类别	示例	目的
功能	`files`、`database`、`api`、`git`	服务器的作用
环境	`development`、`production`、`staging`	使用地点
范围	`local`、`remote`、`frontend`、`backend`	访问范围
目的	`tools`、`monitoring`、`collaboration`	为何需要

添加标签

在 -- 分隔符前使用 --tags 参数：

bash

1mcp mcp add filesystem --tags=files,local -- npx -y @modelcontextprotocol/server-filesystem ./src

创建预设

bash

1mcp preset create dev-tools --filter "development OR tools"
1mcp preset create backend --filter "backend AND development"
1mcp preset create fullstack --filter "(frontend OR backend) AND development"

常见错误

❌ 缺少标签：1mcp mcp add server -- ... ✅ 始终标记：1mcp mcp add server --tags=dev,tools -- ...

❌ 不一致：dev、development、dev-mode ✅ 一致：始终使用 development

调试命令

bash

1mcp mcp list                    # 查看所有服务器和标签
1mcp preset show my-preset       # 查看预设包含哪些服务器
1mcp proxy --filter "..."        # 测试过滤表达式

复杂过滤表达式

json

{
  "filter": "(filesystem AND development) OR (github AND collaboration)"
}

排除逻辑

json

{
  "filter": "web AND NOT test AND NOT debug"
}

故障排除

服务器未找到：1mcp mcp status、1mcp serve（不带 --enable-auth）、用 curl http://localhost:3051/mcp 测试

配置未加载：检查 .1mcprc 是否存在（ls -la .1mcprc）、验证 JSON（cat .1mcprc | jq）、用 1mcp proxy 测试

预设未找到：1mcp preset list、创建它或在 .1mcprc 中使用直接过滤

服务器未显示：1mcp mcp list、验证标签匹配预设过滤、检查 1mcp preset show <name>

Codex 连接失败：

验证代理工作：1mcp proxy
检查 config.toml 语法
确认服务器运行：curl http://localhost:3051/health
重启 Codex

错误的工作目录：从包含 .1mcprc 的项目根目录启动 Codex

标签过滤问题：验证服务器有标签（1mcp mcp list）、检查预设过滤（1mcp preset show <name>）

预设更改被忽略：重启 Codex 和 1MCP 服务器（pkill -f "1mcp.*serve" && 1mcp serve）

调试：1mcp proxy --log-file=proxy.log、1mcp mcp status

性能：使用 1mcp proxy --timeout=30000 增加超时

最佳实践

身份验证：代理不支持身份验证 - 使用不带 --enable-auth 的 1mcp serve
项目结构：将 .1mcprc 保留在项目根目录中，对其进行版本控制（除非包含机密）
标签一致性：在团队中使用标准标签名称
性能：仅加载需要的服务器，对过滤使用一致的标签

后续步骤

创建更多预设：1mcp preset create <name> --filter "<tags>"

团队入门：

在项目 README 中记录设置
共享 .1mcprc 和预设配置（如果不包含机密则可版本控制）
标准化标签约定

优化：

监控健康：1mcp mcp status
固定版本：1mcp mcp add server --tags=stable -- npx -y @org/[email protected]

相关指南：

另请参见

代理命令 - 详细代理命令文档
快速开始 - 基本 1MCP 设置
配置指南 - 高级配置选项
预设命令 - 预设管理命令
MCP 命令 - MCP 服务器管理

Codex 集成 ​

概述 ​

Codex 版本兼容性 ​

Codex < 0.44.0（有限支持） ​

Codex ≥ 0.44.0（HTTP 传输支持） ​

为什么即使在 Codex ≥ 0.44.0 时仍推荐使用 1MCP 代理？ ​

1. 项目特定服务器管理 ​

2. 高级标签过滤 ​

3. 集中式服务器管理 ​

1MCP 桥接解决方案 ​

术语 ​

备选方案：直接 HTTP 传输（Codex ≥ 0.44.0） ​

前置条件 ​

系统要求 ​

安装 ​

配置文件位置 ​

已知问题 ​

验证清单 ​

项目目录 ​

快速开始 ​

1. 安装并启动 1MCP 服务器 ​

2. 创建项目配置 ​

3. 创建预设 ​

4. 配置 Codex ​

5. 在你的项目目录中启动 Codex ​

6. 在 Codex 中测试 ​

架构 ​

1MCP 代理集成（推荐） ​

直接 HTTP 集成（Codex ≥ 0.44.0） ​

关键差异 ​

工作目录要求 ​

配置选项 ​

基本项目配置 ​

带过滤的高级配置 ​

多环境设置 ​

预设管理 ​

创建预设 ​

列出预设 ​

在项目中使用预设 ​

示例：项目特定预设 ​

标签和预设：基本概念 ​

标签为何重要 ​

标签策略 ​

推荐的标签类别 ​

添加标签 ​

创建预设 ​

常见错误 ​

调试命令 ​

复杂过滤表达式 ​

排除逻辑 ​

故障排除 ​

最佳实践 ​

后续步骤 ​

另请参见 ​

Codex 集成

概述

Codex 版本兼容性

Codex < 0.44.0（有限支持）

Codex ≥ 0.44.0（HTTP 传输支持）

为什么即使在 Codex ≥ 0.44.0 时仍推荐使用 1MCP 代理？

1. 项目特定服务器管理

2. 高级标签过滤

3. 集中式服务器管理

1MCP 桥接解决方案

术语

备选方案：直接 HTTP 传输（Codex ≥ 0.44.0）

前置条件

系统要求

安装

配置文件位置

已知问题

验证清单

项目目录

快速开始

1. 安装并启动 1MCP 服务器

2. 创建项目配置

3. 创建预设

4. 配置 Codex

5. 在你的项目目录中启动 Codex

6. 在 Codex 中测试

架构

1MCP 代理集成（推荐）

直接 HTTP 集成（Codex ≥ 0.44.0）

关键差异

工作目录要求

配置选项

基本项目配置

带过滤的高级配置

多环境设置

预设管理

创建预设

列出预设

在项目中使用预设

示例：项目特定预设

标签和预设：基本概念

标签为何重要

标签策略

推荐的标签类别

添加标签

创建预设

常见错误

调试命令

复杂过滤表达式

排除逻辑

故障排除

最佳实践

后续步骤

另请参见