codex-mcp-server-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex MCP Server Integration

Codex MCP Server 集成

Skill by ara.so — MCP Skills collection.

由ara.so提供的Skill — MCP Skills集合。

Overview

概述

Codex MCP Server bridges Claude Code, Cursor, and other MCP-compatible editors with OpenAI's Codex CLI. It provides AI-powered code analysis, generation, review, and web search capabilities through the Model Context Protocol (MCP).

Architecture:

Claude Code/Cursor → Codex MCP Server → Codex CLI → OpenAI API

Codex MCP Server 连接 Claude Code、Cursor 及其他兼容MCP的编辑器与OpenAI的Codex CLI。它通过模型上下文协议（MCP）提供AI驱动的代码分析、生成、评审和网页搜索功能。

架构：

Claude Code/Cursor → Codex MCP Server → Codex CLI → OpenAI API

Installation

安装

Step 1: Install Codex CLI

步骤1：安装Codex CLI

bash

undefined

bash

undefined

Via npm (recommended)

通过npm（推荐）

npm install -g @openai/codex

Via Homebrew

通过Homebrew

brew install codex

Verify installation

验证安装

codex --version # Should be 0.75.0 or higher

undefined

codex --version # 版本应不低于0.75.0

undefined

Step 2: Authenticate Codex CLI

步骤2：验证Codex CLI身份

bash

undefined

bash

undefined

Set your OpenAI API key

设置你的OpenAI API密钥

codex login --api-key "$OPENAI_API_KEY"

Verify authentication

验证身份

codex ping

undefined

codex ping

undefined

Step 3: Install MCP Server

步骤3：安装MCP Server

For Claude Code:

bash

claude mcp add codex-cli -- npx -y codex-mcp-server

Manual configuration (add to MCP settings file):

json

{
  "mcpServers": {
    "codex-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-server"]
    }
  }
}

With static callback URI:

json

{
  "mcpServers": {
    "codex-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-server"],
      "env": {
        "CODEX_MCP_CALLBACK_URI": "http://localhost:8080/mcp-callback"
      }
    }
  }
}

针对Claude Code：

bash

claude mcp add codex-cli -- npx -y codex-mcp-server

手动配置（添加至MCP设置文件）：

json

{
  "mcpServers": {
    "codex-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-server"]
    }
  }
}

使用静态回调URI：

json

{
  "mcpServers": {
    "codex-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-server"],
      "env": {
        "CODEX_MCP_CALLBACK_URI": "http://localhost:8080/mcp-callback"
      }
    }
  }
}

Available Tools

可用工具

1. codex — AI Coding Assistant

1. codex — AI编码助手

The main tool for code analysis, generation, and assistance.

Basic usage:

typescript

// Ask a simple question about code
codex({
  prompt: "Explain what this function does and suggest improvements",
  context: ["src/auth/login.ts"]
})

Parameters:

```
prompt
```
(required): Your question or instruction
```
context
```
(optional): Array of file paths to include
```
sessionId
```
(optional): Resume a previous conversation
```
model
```
(optional): Override model (e.g., "o3", "gpt-4")
```
reasoningEffort
```
(optional): "low", "medium", "high" for reasoning models
```
fullAuto
```
(optional): Enable autonomous mode
```
sandbox
```
(optional): Sandbox permissions ("read-only", "workspace-write")
```
callbackUri
```
(optional): MCP callback URI for this request
```
structuredContent
```
(optional): Return threadId and structured metadata

Response includes:

```
response
```
: The AI's text response
```
threadId
```
: Conversation thread ID (if available from Codex 0.87+)
```
metadata
```
: Additional context about the response

用于代码分析、生成和辅助的核心工具。

基础用法：

typescript

// 询问关于代码的简单问题
codex({
  prompt: "解释这个函数的作用并提出改进建议",
  context: ["src/auth/login.ts"]
})

参数：

```
prompt
```
（必填）：你的问题或指令
```
context
```
（可选）：要包含的文件路径数组
```
sessionId
```
（可选）：恢复之前的对话
```
model
```
（可选）：覆盖默认模型（例如："o3", "gpt-4"）
```
reasoningEffort
```
（可选）：推理模型的级别，可选"low", "medium", "high"
```
fullAuto
```
（可选）：启用自主模式
```
sandbox
```
（可选）：沙箱权限（"read-only", "workspace-write"）
```
callbackUri
```
（可选）：此请求的MCP回调URI
```
structuredContent
```
（可选）：返回threadId和结构化元数据

响应包含：

```
response
```
：AI的文本响应
```
threadId
```
：对话线程ID（Codex 0.87+版本可用）
```
metadata
```
：响应的附加上下文

2. review — Code Review

2. review — 代码评审

AI-powered code review for uncommitted changes, branches, or commits.

Review uncommitted changes:

typescript

review({
  uncommitted: true
})

Review a branch:

typescript

review({
  base: "main",
  head: "feature/new-api"
})

Review specific commits:

typescript

review({
  commit: "abc123..def456"
})

Parameters:

```
uncommitted
```
(optional): Review uncommitted changes
```
base
```
(optional): Base branch for comparison
```
head
```
(optional): Head branch/commit to review
```
commit
```
(optional): Specific commit or range
```
model
```
(optional): Override model
```
reasoningEffort
```
(optional): Reasoning level

针对未提交变更、分支或提交的AI驱动代码评审。

评审未提交变更：

typescript

review({
  uncommitted: true
})

评审分支：

typescript

review({
  base: "main",
  head: "feature/new-api"
})

评审特定提交：

typescript

review({
  commit: "abc123..def456"
})

参数：

```
uncommitted
```
（可选）：评审未提交的变更
```
base
```
（可选）：用于对比的基准分支
```
head
```
（可选）：要评审的目标分支/提交
```
commit
```
（可选）：特定提交或提交范围
```
model
```
（可选）：覆盖默认模型
```
reasoningEffort
```
（可选）：推理级别

3. websearch — Web Search

3. websearch — 网页搜索

Search the web using Codex CLI's integrated search.

typescript

websearch({
  query: "React Server Components best practices 2025",
  numResults: 10,
  searchDepth: "full"
})

Parameters:

```
query
```
(required): Search query
```
numResults
```
(optional): Number of results (default: 10)
```
searchDepth
```
(optional): "quick" or "full" (default: "quick")

使用Codex CLI集成的搜索功能进行网页搜索。

typescript

websearch({
  query: "React Server Components 2025最佳实践",
  numResults: 10,
  searchDepth: "full"
})

参数：

```
query
```
（必填）：搜索查询词
```
numResults
```
（可选）：结果数量（默认：10）
```
searchDepth
```
（可选）："quick"或"full"（默认："quick"）

4. listSessions — View Active Sessions

4. listSessions — 查看活跃会话

List all active conversation sessions for this server instance.

typescript

listSessions()

Returns array of session objects with

id

and

messageCount

列出此服务器实例的所有活跃对话会话。

typescript

listSessions()

返回包含

id

和

messageCount

的会话对象数组。

5. ping — Test Connection

5. ping — 测试连接

Verify the server is responding.

typescript

ping()

验证服务器是否响应。

typescript

ping()

6. help — Get CLI Help

6. help — 获取CLI帮助

Get help information from Codex CLI.

typescript

help({
  command: "review"  // Optional: specific command
})

获取Codex CLI的帮助信息。

typescript

help({
  command: "review"  // 可选：指定命令
})

Common Patterns

常见模式

Multi-Turn Conversations

多轮对话

Use

sessionId

to maintain context across multiple interactions:

typescript

// Start a refactoring session
codex({
  prompt: "Analyze this authentication module for security issues",
  context: ["src/auth/index.ts"],
  sessionId: "auth-refactor"
})

// Continue in the same session
codex({
  prompt: "Implement the security fixes you suggested",
  sessionId: "auth-refactor"
})

// Follow up with more questions
codex({
  prompt: "Add unit tests for the new security checks",
  sessionId: "auth-refactor"
})

// Check active sessions
listSessions()
// Returns: [{ id: "auth-refactor", messageCount: 3 }]

使用

sessionId

在多次交互中维持上下文：

typescript

// 启动重构会话
codex({
  prompt: "分析此认证模块的安全问题",
  context: ["src/auth/index.ts"],
  sessionId: "auth-refactor"
})

// 在同一会话中继续
codex({
  prompt: "实现你建议的安全修复",
  sessionId: "auth-refactor"
})

// 跟进更多问题
codex({
  prompt: "为新的安全检查添加单元测试",
  sessionId: "auth-refactor"
})

// 检查活跃会话
listSessions()
// 返回: [{ id: "auth-refactor", messageCount: 3 }]

Code Analysis Workflows

代码分析工作流

Security audit:

typescript

codex({
  prompt: "Perform a security audit focusing on: 1) Input validation, 2) Authentication bypasses, 3) SQL injection risks, 4) XSS vulnerabilities",
  context: ["src/api/**/*.ts"],
  model: "o3",
  reasoningEffort: "high"
})

Performance optimization:

typescript

codex({
  prompt: "Identify performance bottlenecks and suggest optimizations with Big O analysis",
  context: ["src/services/data-processor.ts"],
  sessionId: "perf-optimization"
})

Refactoring guidance:

typescript

codex({
  prompt: "Suggest refactoring to improve maintainability: extract reusable patterns, reduce complexity, improve naming",
  context: ["src/legacy/user-manager.js"]
})

安全审计：

typescript

codex({
  prompt: "执行安全审计，重点关注：1) 输入验证，2) 身份认证绕过，3) SQL注入风险，4) XSS漏洞",
  context: ["src/api/**/*.ts"],
  model: "o3",
  reasoningEffort: "high"
})

性能优化：

typescript

codex({
  prompt: "识别性能瓶颈并结合大O分析提出优化建议",
  context: ["src/services/data-processor.ts"],
  sessionId: "perf-optimization"
})

重构指导：

typescript

codex({
  prompt: "提出重构建议以提升可维护性：提取可复用模式、降低复杂度、优化命名",
  context: ["src/legacy/user-manager.js"]
})

Pre-Commit Code Review

提交前代码评审

typescript

// Review all uncommitted changes
review({
  uncommitted: true,
  model: "gpt-4"
})

// Review specific branch before PR
review({
  base: "main",
  head: "feature/user-permissions",
  reasoningEffort: "high"
})

typescript

// 评审所有未提交变更
review({
  uncommitted: true,
  model: "gpt-4"
})

// 拉取请求前评审特定分支
review({
  base: "main",
  head: "feature/user-permissions",
  reasoningEffort: "high"
})

Research and Documentation

研究与文档

typescript

// Find latest best practices
websearch({
  query: "TypeScript 5.8 new features decorators",
  numResults: 15,
  searchDepth: "full"
})

// Learn about a library
websearch({
  query: "Prisma vs TypeORM 2025 comparison pros cons",
  numResults: 10
})

// Then ask codex to help implement
codex({
  prompt: "Based on current best practices, help me migrate this ORM code to Prisma",
  context: ["src/models/user.ts"]
})

typescript

// 查找最新最佳实践
websearch({
  query: "TypeScript 5.8新特性装饰器",
  numResults: 15,
  searchDepth: "full"
})

// 了解某个库
websearch({
  query: "Prisma vs TypeORM 2025对比优缺点",
  numResults: 10
})

// 然后让codex协助实现
codex({
  prompt: "基于当前最佳实践，帮助我将此ORM代码迁移到Prisma",
  context: ["src/models/user.ts"]
})

Autonomous Mode with Sandbox

带沙箱的自主模式

For tasks that require file modifications:

typescript

codex({
  prompt: "Implement a REST API endpoint for user registration with validation, error handling, and tests",
  fullAuto: true,
  sandbox: "workspace-write",
  context: ["src/api/routes/"]
})

Sandbox modes:

```
"read-only"
```
: Can read but not modify files
```
"workspace-write"
```
: Can create/modify files in workspace

适用于需要修改文件的任务：

typescript

codex({
  prompt: "实现一个用户注册的REST API端点，包含验证、错误处理和测试",
  fullAuto: true,
  sandbox: "workspace-write",
  context: ["src/api/routes/"]
})

沙箱模式：

```
"read-only"
```
: 可读取但无法修改文件
```
"workspace-write"
```
: 可在工作区创建/修改文件

Using Thread IDs (Codex 0.87+)

使用线程ID（Codex 0.87+）

When using Codex CLI 0.87+, capture thread IDs for conversation tracking:

typescript

const result = codex({
  prompt: "Design a caching strategy for this API",
  context: ["src/api/handlers.ts"],
  structuredContent: true
})

// result.threadId available for tracking
// result.metadata contains additional context

使用Codex CLI 0.87+版本时，捕获线程ID以跟踪对话：

typescript

const result = codex({
  prompt: "为此API设计缓存策略",
  context: ["src/api/handlers.ts"],
  structuredContent: true
})

// result.threadId可用于跟踪
// result.metadata包含附加上下文

Configuration

配置

Environment Variables

环境变量

CODEX_MCP_CALLBACK_URI: Set a static MCP callback URI for all requests.

bash

export CODEX_MCP_CALLBACK_URI="http://localhost:8080/mcp-callback"

This can be overridden per-request using the

callbackUri

parameter in the

codex

tool.

CODEX_MCP_CALLBACK_URI: 为所有请求设置静态MCP回调URI。

bash

export CODEX_MCP_CALLBACK_URI="http://localhost:8080/mcp-callback"

可通过

codex

工具中的

callbackUri

参数按请求覆盖此设置。

Model Selection

模型选择

Override the default model for specific tasks:

typescript

// Use reasoning model for complex logic
codex({
  prompt: "Design a distributed locking mechanism",
  model: "o3",
  reasoningEffort: "high"
})

// Use faster model for simple tasks
codex({
  prompt: "Add JSDoc comments to this function",
  model: "gpt-4-turbo"
})

为特定任务覆盖默认模型：

typescript

// 使用推理模型处理复杂逻辑
codex({
  prompt: "设计分布式锁机制",
  model: "o3",
  reasoningEffort: "high"
})

// 使用更快的模型处理简单任务
codex({
  prompt: "为此函数添加JSDoc注释",
  model: "gpt-4-turbo"
})

Codex CLI Configuration

Codex CLI配置

Check your Codex CLI configuration:

bash

undefined

查看你的Codex CLI配置：

bash

undefined

View current config

查看当前配置

codex config list

Set default model

设置默认模型

codex config set model gpt-4

View authentication status

查看身份验证状态

codex whoami

undefined

codex whoami

undefined

Troubleshooting

故障排除

"Codex CLI not found"

"Codex CLI未找到"

Solution:

bash

undefined

解决方案：

bash

undefined

Verify installation

验证安装

which codex

Reinstall if needed

必要时重新安装

npm install -g @openai/codex@latest

Ensure it's in PATH

确保其在PATH中

echo $PATH

undefined

echo $PATH

undefined

"Authentication failed"

"身份验证失败"

Solution:

bash

undefined

解决方案：

bash

undefined

Re-authenticate

重新验证身份

codex login --api-key "$OPENAI_API_KEY"

Verify key is valid

验证密钥是否有效

codex ping

undefined

codex ping

undefined

"Session not found"

"会话未找到"

Sessions are scoped to the MCP server instance. They reset when the server restarts.

Solution:

List active sessions:
```
listSessions()
```
Start a new session with the same ID to resume conceptually

会话作用域限于MCP服务器实例，服务器重启后会话会重置。

解决方案：

列出活跃会话：
```
listSessions()
```
使用相同ID启动新会话以恢复上下文

"Version compatibility error"

"版本兼容性错误"

Solution:

bash

undefined

解决方案：

bash

undefined

Check Codex CLI version

检查Codex CLI版本

codex --version

Update to latest

更新至最新版本

npm update -g @openai/codex

Minimum required: 0.75.0

最低要求版本：0.75.0

Recommended: 0.87.0+ for thread ID support

推荐版本：0.87.0+以支持线程ID

undefined

undefined

"Model not available"

"模型不可用"

Some models require specific API access.

Solution:

typescript

// Fallback to widely available model
codex({
  prompt: "your prompt",
  model: "gpt-4"  // or omit to use default
})

部分模型需要特定API权限。

解决方案：

typescript

// 回退到广泛可用的模型
codex({
  prompt: "你的指令",
  model: "gpt-4"  // 或省略以使用默认模型
})

Server not responding

服务器无响应

Solution:

bash

undefined

解决方案：

bash

undefined

Test server connection

测试服务器连接

ping()

Restart MCP server in editor

在编辑器中重启MCP服务器

For Claude Code: Reload window or restart

针对Claude Code：重新加载窗口或重启

For Cursor: Reload window

针对Cursor：重新加载窗口

Check MCP logs in editor's output panel

在编辑器的输出面板中查看MCP日志

undefined

undefined

Best Practices

最佳实践

Use sessions for related work: Group related questions in a session to maintain context.
Provide context files: Always include relevant files in the
```
context
```
array for better responses.
Choose appropriate models: Use reasoning models (
```
o3
```
+
```
reasoningEffort: "high"
```
) for complex logic, faster models for simple tasks.
Review before merging: Use
```
review
```
tool on branches before creating PRs.
Leverage web search: Combine
```
websearch
```
with
```
codex
```
to incorporate latest best practices.
Scope sandbox permissions: Use
```
"read-only"
```
by default; only use
```
"workspace-write"
```
when file modifications are needed.
Track conversations: Use
```
structuredContent: true
```
with Codex 0.87+ to capture thread IDs for audit trails.

为相关工作使用会话：将相关问题分组到一个会话中以维持上下文。
提供上下文文件：始终在
```
context
```
数组中包含相关文件以获得更好的响应。
选择合适的模型：使用推理模型（
```
o3
```
+
```
reasoningEffort: "high"
```
）处理复杂逻辑，使用更快的模型处理简单任务。
合并前进行评审：在创建拉取请求前使用
```
review
```
工具评审分支。
利用网页搜索：结合
```
websearch
```
和
```
codex
```
以融入最新最佳实践。
限制沙箱权限：默认使用
```
"read-only"
```
；仅在需要修改文件时使用
```
"workspace-write"
```
。
跟踪对话：在Codex 0.87+版本中使用
```
structuredContent: true
```
捕获线程ID以用于审计跟踪。

Example Integration Script

示例集成脚本

typescript

// workflow-helper.ts - Automated code review workflow

async function preCommitWorkflow() {
  // 1. Review uncommitted changes
  const reviewResult = await review({
    uncommitted: true,
    reasoningEffort: "high"
  });
  
  console.log("Review:", reviewResult.review);
  
  // 2. If issues found, get fix suggestions
  if (reviewResult.issues?.length > 0) {
    const fixes = await codex({
      prompt: `These issues were found in code review:\n${reviewResult.issues.join('\n')}\n\nProvide specific fixes with code examples.`,
      sessionId: "pre-commit-fixes"
    });
    
    console.log("Suggested fixes:", fixes.response);
  }
  
  // 3. Search for related best practices
  const research = await websearch({
    query: "TypeScript error handling best practices 2025",
    numResults: 5
  });
  
  console.log("Best practices:", research.results);
}

// Run before committing
preCommitWorkflow();

typescript

// workflow-helper.ts - 自动化代码评审工作流

async function preCommitWorkflow() {
  // 1. 评审未提交变更
  const reviewResult = await review({
    uncommitted: true,
    reasoningEffort: "high"
  });
  
  console.log("评审结果:", reviewResult.review);
  
  // 2. 如果发现问题，获取修复建议
  if (reviewResult.issues?.length > 0) {
    const fixes = await codex({
      prompt: `代码评审中发现以下问题:\n${reviewResult.issues.join('\n')}\n\n提供包含代码示例的具体修复方案。`,
      sessionId: "pre-commit-fixes"
    });
    
    console.log("建议修复方案:", fixes.response);
  }
  
  // 3. 搜索相关最佳实践
  const research = await websearch({
    query: "TypeScript错误处理2025最佳实践",
    numResults: 5
  });
  
  console.log("最佳实践:", research.results);
}

// 提交前运行
preCommitWorkflow();