Codex Persistent Remote MCP

Codex持久远程MCP服务器

一个安全的、网络可访问的MCP（模型上下文协议）服务器，通过HTTP提供持久的Codex（GPT-5）会话。 无需Codex API密钥 -这只是一个具有Codex访问权限的OpenAI统一费率订阅。此服务器允许您运行Codex AI会话，这些会话可以从网络上的多台计算机访问，具有内置的安全功能和会话管理。

为什么存在

该服务器通过MCP协议将Codex（OpenAI的GPT-5模型）与Claude Code连接起来，实现：

• 无API关键成本：使用您的OpenAI统一费率订阅，而不是基于使用量的计费
• 持续会话：在多个交互中保持Codex对话的活力
• 网络接入：从网络上的任何计算机访问您的Codex实例
• 多个会话：同时运行多个独立的Codex会议
• 安全：内置身份验证、速率限制和IP限制
• 会话管理：自动清理非活动会话

快速开始

1.安装

git clone https://github.com/Jeff31UK/codex-persistent-remote-mcp.git
cd codex-persistent-remote-mcp
npm install

2.生成服务器API密钥（网络访问需要）

openssl rand -hex 32
# Copy this key for securing your MCP server (not for Codex/OpenAI)

3.启动服务器

# Run with API key (required for security)
MCP_API_KEY=your-generated-key AUTO_EXIT=false npm start

4.从克劳德代码连接

# Add the MCP server to Claude Code
claude mcp add --transport http codex-persistent http://YOUR-IP:3000/mcp \
  --header "Authorization: Bearer your-generated-key"

# Find your server IP with:
ip addr show  # Linux/Mac
ipconfig      # Windows

5.在克劳德代码中使用

连接后，您将可以在Claude Code中访问这些工具：

• start_session -启动新的Codex会议
• send_prompt -向Codex发送提示
• end_session -关闭会话
• list_sessions -查看活动会话

特性

🔒 安全功能

• API密钥验证：所有MCP端点的承载令牌身份验证
• 速率限制：每个IP每分钟100个请求（防止滥用）
• IP允许列表：可选IP限制（默认为允许所有）
• CORS 保护：验证源标头
• 网络绑定控制：选择仅本地主机或全网络访问

🚀 会话管理

• 持续会话：请求之间的会话保持活动状态
• 多个会话：运行许多独立的Codex实例
• 自动清理：30分钟后清理不活动会话
• 无自动退出选项：服务器可以无限期运行 AUTO_EXIT=false

🎯 Codex配置

• 模型选择：选择GPT-5推理级别（最低、低、中、高）
• 审批政策：配置命令批准（不受信任、失败、请求、从不）
• 沙盒模式：控制文件系统访问级别

配置选项

环境变量

创建一个 .env 文件（参见 .env.example):

# Server Configuration
PORT=3000                    # Server port (default: 3000)
HOST=0.0.0.0                 # Bind address (0.0.0.0 for network, 127.0.0.1 for localhost)
AUTO_EXIT=false              # Keep running when no sessions (default: true)

# Security (REQUIRED for network access!)
MCP_API_KEY=your-key-here    # API key for authentication
ALLOWED_IPS=                 # Comma-separated IP list (empty = allow all)

食品法典委员会会议选项

启动会话时，您可以配置：

{
  "model": "gpt-5-medium",        // Reasoning effort level
  "approval_policy": "never",      // Command approval policy  
  "sandbox": "read-only",          // File system access level
  "config_options": {              // Additional options
    "model_reasoning_effort": "high"
  }
}

模型选项:

• gpt-5-minimal：反应最快，推理能力有限
• gpt-5-low：速度和推理的平衡
• gpt-5-medium：默认值，固体平衡（推荐）
• gpt-5-high：复杂问题的最大推理能力

沙盒选项:

• none：完全文件系统访问权限（危险！）
• read-only：只读文件
• workspace-write：全部阅读，写入工作区
• danger-full-access：完全访问（谨慎使用）

安全最佳实践

用于本地网络

# Minimum security setup
MCP_API_KEY=$(openssl rand -hex 32)
AUTO_EXIT=false
npm start

用于制作/互联网曝光

1. 始终使用https 使用反向代理：

# nginx.conf
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mcp {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}

1. 限制IP 如果可能：

ALLOWED_IPS=192.168.1.100,192.168.1.101 npm start

1. 使用强API密钥 并定期旋转它们
2. 监控日志 可疑活动
3. 保持服务器更新

部署选项

系统服务（Linux）

创建 /etc/systemd/system/codex-mcp.service:

[Unit]
Description=Codex Persistent MCP Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/codex-persistent-remote-mcp
ExecStart=/usr/bin/npm start
Restart=always
Environment="MCP_API_KEY=your-key"
Environment="AUTO_EXIT=false"

[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl enable codex-mcp
sudo systemctl start codex-mcp

Docker（即将推出）

Docker支持旨在简化部署和隔离。

API终点

• POST /mcp -MCP协议端点（需要身份验证）
• GET /health -健康检查端点（无需身份验证）

故障排除

服务器无法启动

• 检查端口3000是否已在使用中： lsof -i :3000
• 验证Node.js版本： node --version （需要v18+）

无法从Claude Code连接

• 验证服务器是否正在运行： curl http://localhost:3000/health
• 检查防火墙设置是否允许端口3000
• 确保在服务器和客户端中正确设置了API密钥

会话很快超时

• 如果需要，在代码中增加会话超时
• 确保 AUTO_EXIT=false 已设置
• 检查服务器日志是否有错误

身份验证错误

• 验证API密钥是否完全匹配（无额外空格）
• 检查授权标头格式： Bearer your-key
• 确保MCP_API_KEY环境变量已设置

发展

以开发模式运行

npm run dev  # Watches for file changes

项目结构

├── src/
│   ├── index.js          # Entry point
│   ├── server.js         # HTTP server & MCP setup
│   └── sessionManager.js # Codex session management
├── .env.example          # Environment template
├── .gitignore           # Git ignore rules
├── package.json         # Dependencies
└── README.md           # This file

需求

• Node.js v18或更高版本
• Codex CLI已安装并配置
• 使用Codex访问的OpenAI统一费率订阅（不需要API密钥）
• 网络访问（用于远程连接）

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 提交您的更改
4. 推到分支
5. 打开拉取请求

安全披露

发现安全问题？请发送电子邮件至security@yourproject.com而不是使用问题跟踪器。

致谢

• 建立在 模型上下文协议（MCP）
• 使用统一费率订阅与OpenAI的Codex（GPT-5）集成
• 设计用于 克劳德代码
• 无需Codex API密钥或基于使用的计费

支持

• 问题：
• 讨论：

______________________________________________________________________

⚠️ 重要：在没有正确的身份验证和HTTPS的情况下，切勿将此服务器暴露在互联网上！