Connects to OpenAI's Codex CLI to enable code analysis, editing, and automation within your IDE or AI assistant.
Click on "Install 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 explain the architecture of @src/"
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.
Codex MCP Tool is an open‑source Model Context Protocol (MCP) server that connects your IDE or AI assistant (Claude, Cursor, etc.) to the Codex CLI. It enables non‑interactive automation with codex exec, safe sandboxed edits with approvals, and large‑scale code analysis via @ file references. Built for reliability and speed, it streams progress updates, supports structured change mode (OLD/NEW patch output), and integrates cleanly with standard MCP clients for code review, refactoring, documentation, and CI automation.
Latest Release (v1.3.8): Fixed empty
ask-codexresponses, improved Codex CLI transcript parsing, and repaired release packaging so npm/marketplace updates publish correctly. See changelog
Ask Codex questions from your MCP client, or brainstorm ideas programmatically.
Goal: Use Codex directly from your MCP-enabled editor to analyze and edit code efficiently.
Related MCP server: codex-mcp-tool
Before using this tool, ensure you have:
✅ Cross-Platform Support: Fully tested and working on Windows, macOS, and Linux (v1.2.4+)
In Claude Code, run:
/plugin marketplace add etheaven/codex-mcp-server
/plugin install codex-mcp-server@codex-mcp-serverclaude mcp add codex-cli -- npx -y @etheaven/codex-mcp-serverType /mcp inside Claude Code to verify the Codex MCP is active.
Add to your Claude Desktop config file:
{
"mcpServers": {
"codex-cli": {
"command": "npx",
"args": ["-y", "@etheaven/codex-mcp-server"]
}
}
}Config file locations:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json
npm install -g @etheaven/codex-mcp-serverThen use "command": "codex-mcp" instead of the npx approach.
After updating configuration, restart your terminal session.
Natural language: "use codex to explain index.html", "understand this repo with @src", "look for vulnerabilities and suggest fixes"
Claude Code: Type /codex-cli to access the MCP server tools.
// Use the default model (gpt-5.4)
'explain the architecture of @src/';
// Use gpt-5.3-codex for complex coding tasks
'use codex with model gpt-5.3-codex to refactor @legacy-code.js';
// Use gpt-5.4 with high reasoning for deep analysis
'use codex with model gpt-5.4 and reasoning high to analyze complex algorithm in @algorithm.py';
// Use o4-mini for quick tasks
'use codex with model o4-mini to add comments to @utils.js';
// Use o3 for deep reasoning
'use codex with model o3 to design microservices architecture for @requirements.md';
// Use gpt-5-mini for cost-effective tasks
'use codex with model gpt-5-mini to summarize @README.md';ask codex to analyze @src/main.ts and explain what it does
use codex to summarize @. the current directory
analyze @package.json and list dependencies
ask codex to explain div centering
ask codex about best practices for React development related to @src/components/Button.tsx
brainstorm ways to optimize our CI/CD pipeline using SCAMPER method
use codex to brainstorm 10 innovative features for our app with feasibility analysis
ask codex to generate product ideas for the healthcare domain with design-thinking approach
Codex CLI supports fine-grained control over permissions and approvals through sandbox modes and approval policies.
The sandbox Parameter (Convenience Flag):
sandbox: true → Enables fullAuto mode (equivalent to fullAuto: true)
sandbox: false (default) → Does NOT disable sandboxing, just doesn't enable auto mode
Important: The sandbox parameter is a convenience flag, not a security control
Granular Control Parameters:
sandboxMode: Controls file system access level
approvalPolicy: Controls when user approval is required
fullAuto: Shorthand for sandboxMode: "workspace-write" + approvalPolicy: "on-failure"
yolo: ⚠️ Bypasses all safety checks (dangerous, not recommended)
Mode | Description | Use Case |
| Analysis only, no file modifications | Code review, exploration, documentation reading |
| Can modify files in workspace | Most development tasks, refactoring, bug fixes |
| Full system access including network | Advanced automation, CI/CD pipelines |
Policy | Description | When to Use |
| No approvals required | Fully trusted automation |
| Ask before every action | Maximum control, manual review |
| Only ask when operations fail | Balanced automation (recommended) |
| Maximum paranoia mode | Untrusted code or high-risk changes |
Example 1: Balanced Automation (Recommended)
{
"approvalPolicy": "on-failure",
"sandboxMode": "workspace-write", // Auto-set if omitted in v1.2+
"model": "gpt-5.4",
"prompt": "refactor @src/utils for better performance"
}Example 2: Quick Automation (Convenience Mode)
{
"sandbox": true, // Equivalent to fullAuto: true
"model": "gpt-5.4",
"prompt": "fix type errors in @src/"
}Example 3: Read-Only Analysis
{
"sandboxMode": "read-only",
"model": "gpt-5.4",
"prompt": "analyze @src/ and explain the architecture"
}Starting from version 1.2.0, the server automatically applies intelligent defaults to prevent permission errors:
✅ If approvalPolicy is set but sandboxMode is not → auto-sets sandboxMode: "workspace-write"
✅ If search: true or oss: true → auto-sets sandboxMode: "workspace-write" (for network access)
✅ All commands include --skip-git-repo-check to prevent errors in non-git environments
If you encounter ❌ Permission Error: Operation blocked by sandbox policy:
Check 1: Verify sandboxMode
# Ensure you're not using read-only mode for write operations
{
"sandboxMode": "workspace-write", // Not "read-only"
"approvalPolicy": "on-failure"
}Check 2: Use convenience flags
# Let the server handle defaults
{
"sandbox": true, // Simple automation
"prompt": "your task"
}Check 3: Update to latest version
# v1.2+ includes smart defaults to prevent permission errors
npm install -g @etheaven/codex-mcp-server@latestIssue 1: MCP Tool Timeout Error
If you encounter timeout errors when using Codex MCP tools:
# Set the MCP tool timeout environment variable (in milliseconds)
export MCP_TOOL_TIMEOUT=36000000 # 10 hours
# For Windows (PowerShell):
$env:MCP_TOOL_TIMEOUT=36000000
# For Windows (CMD):
set MCP_TOOL_TIMEOUT=36000000Add this to your shell profile (~/.bashrc, ~/.zshrc, or PowerShell profile) to make it permanent.
Issue 2: Codex Cannot Write Files
If Codex responds with permission errors like "Operation blocked by sandbox policy" or "rejected by user approval settings", configure your Codex CLI settings:
Create or edit ~/.codex/config.toml:
# Dynamically generated Codex configuration
model = "gpt-5.4"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
approval_policy = "never"
sandbox_mode = "danger-full-access"
disable_response_storage = true
network_access = true⚠️ Security Warning: The danger-full-access mode grants Codex full file system access. Only use this configuration in trusted environments and for tasks you fully understand.
Configuration File Locations:
macOS/Linux: ~/.codex/config.toml
Windows: %USERPROFILE%\.codex\config.toml
After updating the configuration, restart your MCP client (Claude Desktop, Claude Code, etc.).
use codex to create and run a Python script that processes data
ask codex to safely test @script.py and explain what it does
Default Behavior:
All codex exec commands automatically include --skip-git-repo-check to avoid unnecessary git repository checks, as not all execution environments are git repositories.
This prevents permission errors when running Codex in non-git directories or when git checks would interfere with automation.
// Using ask-codex with specific model and reasoning effort
'ask codex using gpt-5.3-codex with reasoning high to refactor @utils/database.js for better performance';
// Brainstorming with constraints
"brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'";
// Change mode for structured edits
'use codex in change mode to update all console.log to use winston logger in @src/';These tools are designed to be used by the AI assistant.
ask-codex: Sends a prompt to Codex via codex exec.
Supports @ file references for including file content
Optional model parameter — recommended models:
gpt-5.4 (default, latest flagship)
gpt-5.3-codex (best for complex coding)
gpt-5.3-codex-spark (instant coding, Pro only)
o3 (deep reasoning)
o4-mini (fast & efficient)
gpt-5-mini (cost-effective)
gpt-4.1 (1M context, no reasoning)
See full model list
Optional reasoningEffort parameter: none, minimal, low, medium, high, xhigh
sandbox=true enables --full-auto mode
changeMode=true returns structured OLD/NEW edits
Supports approval policies and sandbox modes
Automatically includes --skip-git-repo-check to prevent permission errors in non-git environments
brainstorm: Generate novel ideas with structured methodologies.
Multiple frameworks: divergent, convergent, SCAMPER, design-thinking, lateral
Domain-specific context (software, business, creative, research, product, marketing)
Supports same models and reasoningEffort as ask-codex
Configurable idea count and analysis depth
Includes feasibility, impact, and innovation scoring
Example: brainstorm prompt:"ways to improve code review process" domain:"software" methodology:"scamper"
ping: A simple test tool that echoes back a message.
Use to verify MCP connection is working
Example: /codex-cli:ping (MCP) "Hello from Codex MCP!"
help: Shows the Codex CLI help text and available commands.
fetch-chunk: Retrieves cached chunks from changeMode responses.
Used for paginating large structured edit responses
Requires cacheKey and chunkIndex parameters
timeout-test: Test tool for timeout prevention.
Runs for a specified duration in milliseconds
Useful for testing long-running operations
You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested).
/analyze: Analyzes files or directories using Codex, or asks general questions.
prompt (required): The analysis prompt. Use @ syntax to include files (e.g., /analyze prompt:@src/ summarize this directory) or ask general questions (e.g., /analyze prompt:Please use a web search to find the latest news stories).
/sandbox: Safely tests code or scripts with Codex approval modes.
prompt (required): Code testing request (e.g., /sandbox prompt:Create and run a Python script that processes CSV data or /sandbox prompt:@script.py Test this script safely).
/help: Displays the Codex CLI help information.
/ping: Tests the connection to the server.
message (optional): A message to echo back.
📦 Release Fix:
Added search-insights to devDependencies so npm ci passes in the GitHub release workflow
This is the first publishable release that includes the empty ask-codex response fix
📦 Release Fix:
Synced package-lock.json with package.json so the GitHub release workflow can complete npm ci and publish successfully
Carries forward the empty ask-codex response fix from the failed v1.3.6 release attempt
🐛 Bug Fixes:
Fixed empty ask-codex responses when Codex CLI emitted the usable transcript on stderr
Reworked output parsing to handle role-based transcript sections like user, codex, and assistant
Prevented the formatter from returning a bare **Response:** header when no response content was parsed
📦 Release Metadata:
Synced npm, lockfile, and Claude marketplace/plugin metadata to version 1.3.6
Model Support Overhaul:
Updated model list to March 2026: added gpt-5.4, gpt-5.4-pro, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5-pro, gpt-5-mini, gpt-5-nano, o3-pro, gpt-4.1-mini, gpt-4.1-nano
Removed deprecated models: codex-1 and codex-mini-latest (never existed in OpenAI API)
New reasoningEffort parameter for ask-codex, brainstorm, and batch-codex tools — supports none, minimal, low, medium, high, xhigh
Improved tool schema descriptions with exact valid model IDs to prevent AI clients from inventing model names
Updated default model recommendation from gpt-5-codex to gpt-5.4
Comprehensive model documentation rewrite with per-model reasoning effort support tables
🔧 Major Improvement:
Windows Compatibility Enhancement: Replaced Node.js native spawn() with industry-standard cross-spawn package
Root cause: Previous shell: true fix still failed on some Windows configurations
Solution: Use cross-spawn (50M+ weekly downloads, used by Webpack/Jest) for automatic Windows .cmd handling
Benefits:
Zero configuration required for Windows users
Automatic handling of .cmd, .ps1, and .exe extensions
Compatible with both CMD and PowerShell environments
<5ms performance overhead
Dependencies: Added cross-spawn@^7.0.6 and @types/cross-spawn
🐛 Bug Fixes:
Enhanced ENOENT error diagnostics with Windows-specific 4-step troubleshooting guide
Added optional chaining for stdout/stderr to handle null values in TypeScript strict mode
📝 Documentation:
Added comprehensive Windows troubleshooting section in docs
Documented spawn codex ENOENT error resolution steps
🐛 Bug Fixes:
Windows Compatibility: Fixed Codex CLI detection failing on Windows despite proper installation
Root cause: spawn() with shell: false couldn't resolve .cmd extensions on Windows
Solution: Enabled shell mode for cross-platform command execution
Impact: Zero performance impact (~10ms overhead), maintains security with array-form arguments
Platforms verified: Windows, macOS, Linux via GitHub Actions CI
📝 Documentation:
Updated all package references from @trishchuk/codex-mcp-tool to @etheaven/codex-mcp-server (now hosted at etheaven/codex-mcp-server)
Enhanced cross-platform setup instructions
🔍 Testing:
CI/CD now validates on Ubuntu, macOS, and Windows across Node.js 18.x, 20.x, and 22.x
Smart sandbox mode defaults to prevent permission errors
Enhanced debug information for troubleshooting
Automatic --skip-git-repo-check flag for non-git environments
Web search integration with feature flags
Structured change mode with pagination support
Platform | Status | Notes |
Windows | ✅ Fully Supported | Enhanced in v1.2.4 with cross-spawn |
macOS | ✅ Fully Supported | Tested on Darwin 23.5.0+ |
Linux | ✅ Fully Supported | Tested on Ubuntu Latest |
Minimum Requirements:
Node.js v18.0.0 or higher
Codex CLI installed and authenticated (npm install -g @openai/codex)
This project was inspired by the excellent work from jamubc/gemini-mcp-tool. Special thanks to @jamubc for the original MCP server architecture and implementation patterns.
Contributions are welcome! Please submit pull requests or report issues through GitHub.
This project is licensed under the MIT License. See the LICENSE file for details.
Disclaimer: This is an unofficial, third-party tool and is not affiliated with, endorsed, or sponsored by OpenAI.
Use OpenAI Codex to analyze, review, edit, or generate code. Call this tool whenever the user mentions "codex", "use codex", or wants to leverage OpenAI models (GPT-5.4, GPT-5.3-codex, etc.) for code tasks. Supports file references with @ syntax (e.g. @src/), model selection, reasoning effort control, and structured edits via changeMode.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Task or question. Use @ to include files (e.g., '@largefile.ts explain'). | |
| model | No | Model ID to use. IMPORTANT: Use exact IDs listed below, do NOT invent or modify model names. Recommended (use in this order): gpt-5.4 (default, best), gpt-5.3-codex (best coding), gpt-5.3-codex-spark (instant, Pro only), gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano. Large context (1M): gpt-4.1, gpt-4.1-mini, gpt-4.1-nano. | |
| reasoningEffort | No | Reasoning effort level. Controls depth of internal reasoning. Values: none, minimal, low, medium (default), high, xhigh. Higher = deeper analysis but slower and more expensive. Not all models support all levels. gpt-5.4 supports: none/low/medium/high/xhigh. gpt-5.3-codex supports: low/medium/high/xhigh. o3/o4-mini support: low/medium/high. | |
| sandbox | No | Quick automation mode: enables workspace-write + on-failure approval. Alias for fullAuto. | |
| fullAuto | No | Full automation mode | |
| approvalPolicy | No | Approval: never, on-request, on-failure, untrusted | |
| approval | No | Approval policy: untrusted, on-failure, on-request, never | |
| sandboxMode | No | Access: read-only, workspace-write, danger-full-access | |
| yolo | No | ⚠️ Bypass all safety (dangerous) | |
| cd | No | Working directory | |
| workingDir | No | Working directory for execution | |
| changeMode | No | Return structured OLD/NEW edits for refactoring | |
| chunkIndex | No | Chunk index (1-based) | |
| chunkCacheKey | No | Cache key for continuation | |
| image | No | Optional image file path(s) to include with the prompt | |
| config | No | Configuration overrides as 'key=value' string or object | |
| profile | No | Configuration profile to use from ~/.codex/config.toml | |
| timeout | No | Maximum execution time in milliseconds (optional) | |
| includeThinking | No | Include reasoning/thinking section in response | |
| includeMetadata | No | Include configuration metadata in response | |
| search | No | Enable web search by activating web_search_request feature flag. Requires network access - automatically sets sandbox to workspace-write if not specified. | |
| oss | No | Use local Ollama server (convenience for -c model_provider=oss). Requires Ollama running locally. Automatically sets sandbox to workspace-write if not specified. | |
| enableFeatures | No | Enable feature flags (repeatable). Equivalent to -c features.<name>=true | |
| disableFeatures | No | Disable feature flags (repeatable). Equivalent to -c features.<name>=false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the full burden. It mentions file references, model selection, and changeMode, but omits critical behaviors like destructive actions (yolo), automation modes, and safety implications. Lacks depth for a complex tool.
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?
Two sentences covering purpose, trigger, and key features. No redundancy, well front-loaded with essential information.
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?
No output schema, yet the description does not mention what the tool returns. Despite 100% schema coverage, the lack of return value description and incomplete coverage of automation features makes it inadequate for a tool with 24 parameters.
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 baseline is 3. The description adds high-level context (e.g., @ syntax, changeMode) but does not significantly enhance understanding beyond the schema's parameter descriptions.
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 uses OpenAI Codex for code tasks (analyze, review, edit, generate). It specifies when to call it (when user mentions 'codex' or wants OpenAI models), distinguishing it from sibling tools like batch-codex or brainstorm.
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?
Explicitly states to call when user mentions 'codex' or wants OpenAI models for code tasks. Does not provide explicit when-not-to-use scenarios, but the trigger conditions are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run multiple tasks through OpenAI Codex in batch. Use when the user wants Codex to handle several tasks sequentially — mass refactoring, bulk code changes, or automated transformations.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | Array of atomic tasks to delegate to Codex | |
| model | No | Model ID. Recommended order: gpt-5.4 (default), gpt-5.3-codex (coding), gpt-5.2-codex, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini. | |
| reasoningEffort | No | Reasoning effort: none, minimal, low, medium, high, xhigh. | |
| sandbox | No | Sandbox mode: read-only, workspace-write, danger-full-access | workspace-write |
| parallel | No | Execute tasks in parallel (experimental) | |
| stopOnError | No | Stop execution if any task fails | |
| timeout | No | Maximum execution time per task in milliseconds | |
| workingDir | No | Working directory for execution | |
| search | No | Enable web search for all tasks (activates web_search_request feature) | |
| oss | No | Use local Ollama server | |
| enableFeatures | No | Enable feature flags | |
| disableFeatures | No | Disable feature flags |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must cover behavioral traits. It mentions 'batch' and 'sequential' execution, implying multiple tasks. However, it does not disclose potential side effects, authentication needs, rate limits, or what happens on failure. The 'automated transformations' hint at code changes, but this is not explicit.
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 concise: two sentences front-load the purpose and usage, with no wasted words. Every sentence adds value.
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 high schema coverage, the tool has 12 parameters and no output schema. The description does not explain return behavior, error handling, or how parallel/stopOnError work. This leaves gaps for an agent selecting the 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?
Schema description coverage is 100%, so the description does not need to detail each parameter. The description mentions 'several tasks' and 'mass refactoring,' which aligns with the 'tasks' parameter but adds little beyond the schema. Baseline 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 the tool's purpose: 'Run multiple tasks through OpenAI Codex in batch.' It specifies the verb ('run'), the resource ('OpenAI Codex'), and the batch nature, distinguishing it from single-task siblings like 'ask-codex'.
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 clear usage context: 'Use when the user wants Codex to handle several tasks sequentially.' It gives examples like mass refactoring and bulk code changes. However, it does not explicitly mention when not to use this tool or name alternative tools for single tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brainstorm ideas using OpenAI Codex with structured frameworks (SCAMPER, design-thinking, lateral, etc.). Use when the user wants creative ideation, brainstorming, or idea generation via Codex.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Brainstorming challenge or question | |
| model | No | Model ID. Recommended order: gpt-5.4 (default), gpt-5.3-codex (coding), gpt-5.2-codex, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1. | |
| reasoningEffort | No | Reasoning effort: none, minimal, low, medium (default), high, xhigh. Higher = deeper analysis, slower, more expensive. | |
| approvalPolicy | No | Approval: never, on-request, on-failure, untrusted | |
| sandboxMode | No | Access: read-only, workspace-write, danger-full-access | |
| fullAuto | No | Full automation mode | |
| yolo | No | ⚠️ Bypass all safety (dangerous) | |
| cd | No | Working directory | |
| methodology | No | Framework: divergent, convergent, scamper, design-thinking, lateral, auto (default) | auto |
| domain | No | Domain: software, business, creative, research, product, marketing, etc. | |
| constraints | No | Limitations: budget, time, technical, legal, etc. | |
| existingContext | No | Background info or previous attempts | |
| ideaCount | No | Number of ideas (default: 12, range: 5-30) | |
| includeAnalysis | No | Include feasibility/impact analysis | |
| search | No | Enable web search for research (activates web_search_request feature) | |
| oss | No | Use local Ollama server | |
| enableFeatures | No | Enable feature flags | |
| disableFeatures | No | Disable feature flags |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It fails to disclose behavioral traits such as costs, rate limits, auth requirements, or that it uses an AI model (Codex).
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 two sentences and front-loaded with the main purpose. The second sentence is somewhat redundant but not excessively verbose.
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?
The tool has 18 parameters and no output schema, but the description is minimal. It does not explain return values or how to effectively use advanced parameters like methodology, domain, etc.
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% and parameter descriptions in the schema are detailed. The description adds no additional meaning beyond the schema, so baseline 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 states the tool brainstorms ideas using OpenAI Codex with structured frameworks. It distinguishes from siblings like ask-codex (Q&A) and batch-codex (batch processing).
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 says to use when the user wants creative ideation, brainstorming, or idea generation via Codex. It provides clear context but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves cached chunks from a changeMode response. Use this to get subsequent chunks after receiving a partial changeMode response.
| Name | Required | Description | Default |
|---|---|---|---|
| cacheKey | Yes | The cache key provided in the initial changeMode response | |
| chunkIndex | Yes | Which chunk to retrieve (1-based index) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear full burden. However, it only describes the operation without disclosing behavioral traits such as side effects, rate limits, or authentication needs. It merely restates the purpose.
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 consists of two short, direct sentences with no extraneous information. It is optimally concise and front-loaded with the core 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 simplicity of the tool (2 parameters, no output schema, no annotations), the description adequately covers purpose and usage. It could be more detailed about return format or chunk count, but is sufficient for a retrieval 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?
Schema description coverage is 100%. The description adds context that 'cacheKey' comes from the initial changeMode response and that 'chunkIndex' is 1-based, which is helpful beyond the schema's individual descriptions.
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 'retrieves' and the resource 'cached chunks from a changeMode response'. It is distinct from sibling tools which are unrelated (e.g., ask-codex, brainstorm, version).
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 explicitly states when to use the tool: 'Use this to get subsequent chunks after receiving a partial changeMode response'. It does not mention when not to use or provide alternatives, but 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.
receive help information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but 'receive help information' reveals zero details about side effects, permissions, or limitations.
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 extremely short (two words) but lacks sufficient detail, making it under-specified rather than concise.
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 params, no output schema), the description fails to explain what 'help information' means or how to use the tool, leaving major gaps.
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 tool has zero parameters and 100% schema coverage, so the description does not add meaning beyond the empty schema. Baseline 3 is appropriate as it offers no extra parameter insight.
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 'receive help information' states a verb and resource, but it is vague and does not specify what type of help or how it relates to other tools like ask-codex or brainstorm.
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. Sibling tools suggest a range of functionalities, but the description offers no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Echo
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Message to echo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only says 'Echo', which provides almost no behavioral details (e.g., no side effects, return behavior, or permission requirements). This is insufficient for a safe and informed selection.
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?
At one word, the description is extremely concise but underspecified. It sacrifices clarity for brevity, similar to the LOW example 'Process'. Every sentence should earn its place; here there is only one word that could be expanded.
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 is simple (one optional param, no output schema), the description 'Echo' is barely adequate. It implies the tool returns the input, but does not explicitly state return behavior or other context. Minimal completeness for a trivial 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?
Schema description coverage is 100% for the single parameter 'prompt' with description 'Message to echo'. The description 'Echo' adds no additional meaning beyond what the schema already provides, so baseline 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 'Echo' indicates the tool will repeat back the input, but it lacks specificity about the verb and resource. It is not a tautology (name is 'ping', description is different) but is vague on the precise action.
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 its siblings such as 'ask-codex' or 'fetch-chunk'. There is no context on prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test timeout prevention by running for a specified duration
| Name | Required | Description | Default |
|---|---|---|---|
| duration | Yes | Duration in milliseconds (minimum 10ms) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose key behavioral traits such as whether the tool blocks execution, what it returns, or any side effects. Only the basic action of running for a duration is mentioned.
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 extremely concise, consisting of one sentence with no wasted words. It is front-loaded with the purpose, but could benefit from a bit more detail.
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's simplicity, the description lacks important context such as what the test result looks like or whether the tool is safe to run in production. It is incomplete for an agent to fully understand the tool's behavior.
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 coverage is 100% with a clear description for the single 'duration' parameter. The tool description adds no additional semantic information beyond the schema.
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's purpose: testing timeout prevention by running for a specified duration. It distinguishes itself from siblings which are mostly code assistance or network utilities.
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 explicit guidance on when to use this tool vs alternatives. The description does not mention when not to use it or provide any context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Display version and system information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description accurately indicates a read-only info retrieval. Lacks explicit mention of safety but benign nature is clear.
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 sentence, no redundancy, front-loaded. Every word 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?
Adequate for a simple tool with no parameters or output schema. Could specify what 'system information' includes, but not essential.
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?
No parameters needed; schema coverage 100%. Baseline for 0 parameters is 4, and description correctly implies no parameters.
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?
Clearly states verb 'Display' and resource 'version and system information', 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?
No guidance on when to use this tool vs siblings like Help, ping, etc. Usage context is implicit but not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes: ask-codex for general code tasks, batch-codex for sequential tasks, brainstorm for ideation, and utility tools. There is slight overlap between ask-codex and batch-codex, but descriptions clarify the difference.
Tool names mostly follow a lowercase hyphenated pattern (ask-codex, batch-codex, fetch-chunk, timeout-test), but 'Help' is capitalized, breaking consistency. The mix of codex-specific and generic utility names also reduces pattern clarity.
8 tools is a reasonable number for a Codex integration server. Includes core functionality (ask-codex, batch-codex, brainstorm), response retrieval (fetch-chunk), and utilities (help, ping, timeout-test, version). Slightly weighted with utilities, but still well-scoped.
The tool surface covers primary use cases: code analysis/generation, batch processing, brainstorming, and partial response handling. Minor gaps exist (e.g., no explicit code review tool separate from ask-codex), but core workflows are supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/etheaven/codex-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
