Provides integration with OpenAI's Codex CLI, enabling AI-powered code analysis, generation, review, and web search through tools like 'codex', 'review', and 'websearch'.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codex-mcp-server Use codex to review my uncommitted changes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Bridge between Claude and OpenAI's Codex CLI — get AI-powered code analysis, generation, and review right in your editor.
graph LR
A[Claude Code] --> B[Codex MCP Server]
B --> C[Codex CLI]
C --> D[OpenAI API]
style A fill:#FF6B35
style B fill:#4A90E2
style C fill:#00D4AA
style D fill:#FFA500npm i -g @openai/codex
codex login --api-key "your-openai-api-key"claude mcp add codex-cli -- npx -y codex-mcp-serverAsk codex to explain this function
Use codex to refactor this code for better performance
Use review to check my uncommitted changesRelated MCP server: Session Buddy
Tool | Description |
| AI coding assistant with session support, model selection, and structured output metadata |
| AI-powered code review for uncommitted changes, branches, or commits |
| Web search using Codex CLI with customizable result count and search depth |
| View active conversation sessions |
| Test server connection |
| Get Codex CLI help |
Code analysis:
Use codex to analyze this authentication logic for security issuesMulti-turn conversations:
Use codex with sessionId "refactor" to analyze this module
Use codex with sessionId "refactor" to implement your suggestionsPassing a sessionId creates the session on first use, so listSessions will show it (for this server instance) and subsequent calls can resume context.
Code review:
Use review with base "main" to check my PR changes
Use review with uncommitted true to review my local changesAdvanced options:
Use codex with model "o3" and reasoningEffort "high" for complex analysis
Use codex with fullAuto true and sandbox "workspace-write" for automated tasks
Use codex with callbackUri "http://localhost:1234/callback" for static callbacks
Use codex to return structuredContent with threadId metadata when availableWeb search:
Use websearch with query "TypeScript 5.8 new features"
Use websearch with query "Rust vs Go performance 2025" and numResults 15
Use websearch with query "React Server Components" and searchDepth "full"Codex CLI v0.75.0+ — Install with npm i -g @openai/codex or brew install codex
OpenAI API key — Run codex login --api-key "your-key" to authenticate
Thread ID + structured output: When Codex CLI emits threadId, this server returns it in content metadata and structuredContent, and advertises an outputSchema for structured responses.
API Reference — Full tool parameters and response formats
Session Management — How conversations work
Codex CLI Integration — Version compatibility and CLI details
CODEX_MCP_CALLBACK_URI: Static MCP callback URI passed to Codex when set (overridden by callbackUri tool arg)
npm install # Install dependencies
npm run dev # Development mode
npm run build # Build for production
npm test # Run testsgemini-mcp-server — MCP server for Gemini CLI with 1M+ token context, web search, and media analysis
Clotch — Dynamic Island for Claude Code on macOS — monitor sessions across multiple machines and providers in real time
ISC
Execute Codex CLI in non-interactive mode for AI assistance
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The coding task, question, or analysis request | |
| sessionId | No | Optional session ID for conversational context. Note: when resuming a session, sandbox/fullAuto/workingDirectory parameters are not applied (CLI limitation) | |
| resetSession | No | Reset the session history before processing this request | |
| model | No | Specify which model to use (defaults to gpt-5.3-codex). Options: gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5-codex, gpt-4o, gpt-4, o3, o4-mini | |
| reasoningEffort | No | Control reasoning depth (none < minimal < low < medium < high < xhigh) | |
| sandbox | No | Sandbox policy for shell command execution. read-only: no writes allowed, workspace-write: writes only in workspace, danger-full-access: full system access (dangerous) | |
| fullAuto | No | Enable full-auto mode: sandboxed automatic execution without approval prompts (equivalent to -a on-request --sandbox workspace-write) | |
| workingDirectory | No | Working directory for the agent to use as its root (passed via -C flag) | |
| callbackUri | No | Static MCP callback URI to pass to Codex via environment (if provided) |
| Name | Required | Description |
|---|---|---|
| threadId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds 'non-interactive mode', which clarifies that the tool runs without user prompts, a behavioral trait not captured in annotations. This adds moderate value beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. It efficiently conveys the core purpose without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (9 parameters, destructive hint, open world hint), the description is very brief and lacks details on side effects, return values, or usage scenarios. The openWorldHint suggests potential external impacts, but the description does not address this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 9 parameters, so the baseline is 3. The description does not add any additional parameter meaning beyond what the schema already provides, thus a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute Codex CLI in non-interactive mode for AI assistance', specifying the verb 'Execute' and the resource 'Codex CLI'. It distinguishes from sibling tools like 'help', 'listSessions', 'ping', 'review', and 'websearch' by focusing on code execution for AI-driven tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or when not to use it. It lacks explicit context for usage, such as prerequisites or exclusions, which is critical given the presence of sibling tools with overlapping purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Codex CLI help information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds minimal behavioral context beyond 'Get help information'. With annotations covering the safety profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase with no unnecessary words. It is front-loaded and directly conveys the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description adequately covers its purpose. It could optionally mention what kind of help (e.g., command list, usage guide), but it's sufficient for a simple help tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100%. The description adds no parameter details, which is acceptable when there are none. Baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Codex CLI help information' clearly states the action (get) and resource (help information). It distinguishes from siblings like codex or listSessions, which serve different purposes. However, it's somewhat generic and could be more specific about the scope of help.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like codex or review. Since there are no parameters, usage is straightforward, but the description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active conversation sessions with metadata
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds the qualifier 'active' and mentions metadata, which is consistent and adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the purpose without any filler or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no parameters, clear annotations, no output schema), the description is complete and provides sufficient information for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description does not need to add parameter information, as there are none. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all active conversation sessions with metadata, using a specific verb and resource. It distinguishes itself from sibling tools which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (listing sessions) but does not explicitly state when to use or not use versus alternatives. However, sibling tools are distinct, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test MCP server connection
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Message to echo back |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds minimal behavioral context beyond stating it's a connection test. It doesn't discuss side effects, errors, or performance, but annotations cover the safety profile adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no unnecessary words. Every word is meaningful and efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple ping/health-check tool with no output schema and rich annotations, the description is adequate. It informs the agent of the core function. However, missing details like return value behavior could be improved, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'message' parameter, which has a clear description 'Message to echo back'. The tool description does not add further parameter semantics, but the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Test MCP server connection', which is a specific verb (test) and resource (MCP server connection). It distinguishes from sibling tools like 'agy', 'changelog', 'help', and 'listSessions' which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no explicit when-not-to-use, and no mention of prerequisites or context. The description is too minimal to inform selection decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a code review against the current repository using Codex CLI
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Custom review instructions or focus areas (cannot be used with uncommitted=true; use base/commit review instead) | |
| uncommitted | No | Review staged, unstaged, and untracked changes (working tree) - cannot be combined with custom prompt | |
| base | No | Review changes against a specific base branch (e.g., "main", "develop") | |
| commit | No | Review the changes introduced by a specific commit SHA | |
| title | No | Optional title to display in the review summary | |
| model | No | Specify which model to use for the review (defaults to gpt-5.3-codex) | |
| workingDirectory | No | Working directory to run the review in (passed via -C as a global Codex option) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds no additional behavioral context, so it meets the baseline but does not enrich beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly conveys the tool's purpose. It is concise and front-loaded, though it could be slightly more structured with additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description is minimal. It does not explain the review process, output format, or provide examples, leaving significant gaps for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to add parameter meaning. The main description adds no extra insight over the schema, maintaining the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'run' and the resource 'code review against current repository', distinguishing it from sibling tools like 'codex' which is a general tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or context, leaving the agent to infer usage from the tool name and schema constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform web search using Codex CLI with web search enabled
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query to execute | |
| numResults | No | Number of search results to return (1-50, default: 10) | |
| searchDepth | No | Search depth: basic (faster) or full (deeper analysis, default: basic) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds minimal context about the execution environment ('using Codex CLI with web search enabled'), but doesn't disclose additional behavioral traits beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters well-documented in schema, no output schema, and comprehensive annotations, the description covers the essentials. However, it could provide more context about the output format or what 'Codex CLI' refers to, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 3 parameters. The description adds no parameter-specific information beyond what's in the schema, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Perform' and resource 'web search', distinguishing it from sibling tools like 'codex' or 'help'. It's specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, nor does it mention any exclusions or prerequisites. It simply states what it does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.4.10codexhelplistSessionspingreviewwebsearchScored across 6 tools
Each tool has a clearly distinct purpose: general execution, help, session listing, connectivity test, code review, and web search. No overlaps or ambiguity.
Naming is inconsistent: 'listSessions' uses camelCase while all other tools (codex, help, ping, review, websearch) use lowercase. A consistent style pattern is missing.
With 6 tools, the set is well-scoped for a Codex CLI server. Each tool serves a distinct need without bloat or deficiency.
Covers core workflows (execution, help, sessions, connectivity, code review, web search). Minor gap: no explicit session creation/termination, but listing is provided and general execution may cover it.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Live SEO workflow tools for Claude Code, Codex, and AI agents.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
