Skip to main content
Glama
cexll

Codex MCP Server

by cexll
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Codex MCP Tool

GitHub Release npm version npm downloads License: MIT Open Source

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.2.4): Enhanced Windows compatibility - Now using cross-spawn for reliable npm global command execution across all platforms (Windows, macOS, Linux). See changelog

  • Ask Codex questions from your MCP client, or brainstorm ideas programmatically.

TLDR: Claude + Codex CLI

Goal: Use Codex directly from your MCP-enabled editor to analyze and edit code efficiently.

Related MCP server: codex-mcp-server

Prerequisites

Before using this tool, ensure you have:

  1. Node.js (v18.0.0 or higher)

  2. Codex CLI installed and authenticated

✅ Cross-Platform Support: Fully tested and working on Windows, macOS, and Linux (v1.2.4+)

One-Line Setup

claude mcp add codex-cli -- npx -y @cexll/codex-mcp-server

Verify Installation

Type /mcp inside Claude Code to verify the Codex MCP is active.

Alternative: Import from Claude Desktop

If you already have it configured in Claude Desktop:

  1. Add to your Claude Desktop config:

"codex-cli": {
  "command": "npx",
  "args": ["-y", "@cexll/codex-mcp-server"]
}

  1. Import to Claude Code:

claude mcp add-from-claude-desktop

Configuration

Register the MCP server with your MCP client:

For NPX Usage (Recommended)

Add this configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@cexll/codex-mcp-server"]
    }
  }
}

For Global Installation

If you installed globally, use this configuration instead:

{
  "mcpServers": {
    "codex-cli": {
      "command": "codex-mcp"
    }
  }
}

Configuration File Locations:

  • Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • Linux: ~/.config/claude/claude_desktop_config.json

After updating the configuration, restart your terminal session.

Example Workflow

  • 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.

Usage Examples

Model Selection

// Use the default gpt-5-codex model
'explain the architecture of @src/';

// Use gpt-5 for fast general purpose reasoning
'use codex with model gpt-5 to analyze @config.json';

// Use o3 for deep reasoning tasks
'use codex with model o3 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 codex-1 for software engineering
'use codex with model codex-1 to refactor @legacy-code.js';

With File References (using @ syntax)

  • 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

General Questions (without files)

  • ask codex to explain div centering

  • ask codex about best practices for React development related to @src/components/Button.tsx

Brainstorming & Ideation

  • 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 Approvals & Sandbox

Codex CLI supports fine-grained control over permissions and approvals through sandbox modes and approval policies.

Understanding Parameters

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)

Sandbox Modes

Mode

Description

Use Case

read-only

Analysis only, no file modifications

Code review, exploration, documentation reading

workspace-write

Can modify files in workspace

Most development tasks, refactoring, bug fixes

danger-full-access

Full system access including network

Advanced automation, CI/CD pipelines

Approval Policies

Policy

Description

When to Use

never

No approvals required

Fully trusted automation

on-request

Ask before every action

Maximum control, manual review

on-failure

Only ask when operations fail

Balanced automation (recommended)

untrusted

Maximum paranoia mode

Untrusted code or high-risk changes

Configuration Examples

Example 1: Balanced Automation (Recommended)

{
  "approvalPolicy": "on-failure",
  "sandboxMode": "workspace-write",  // Auto-set if omitted in v1.2+
  "model": "gpt-5-codex",
  "prompt": "refactor @src/utils for better performance"
}

Example 2: Quick Automation (Convenience Mode)

{
  "sandbox": true,  // Equivalent to fullAuto: true
  "model": "gpt-5-codex",
  "prompt": "fix type errors in @src/"
}

Example 3: Read-Only Analysis

{
  "sandboxMode": "read-only",
  "model": "gpt-5-codex",
  "prompt": "analyze @src/ and explain the architecture"
}

Smart Defaults (v1.2+)

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

Troubleshooting Permission Errors

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 @cexll/codex-mcp-server@latest

Common Issues

Issue 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=36000000

Add 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-codex"
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.).

Basic Examples

  • 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.

Advanced Examples

// Using ask-codex with specific model
'ask codex using gpt-5 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/';

Tools (for the AI)

These tools are designed to be used by the AI assistant.

Core Tools

  • ask-codex: Sends a prompt to Codex via codex exec.

    • Supports @ file references for including file content

    • Optional model parameter - available models:

      • gpt-5-codex (default, optimized for coding)

      • gpt-5 (general purpose, fast reasoning)

      • o3 (smartest, deep reasoning)

      • o4-mini (fast & efficient)

      • codex-1 (o3-based for software engineering)

      • codex-mini-latest (low-latency code Q&A)

      • gpt-4.1 (also available)

    • 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 as ask-codex (default: gpt-5-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.

Advanced Tools

  • 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

Slash Commands (for the User)

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.

Recent Updates

v1.2.4 (2025-10-27)

🔧 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

v1.2.3 (2025-10-27)

🐛 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 @cexll/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

v1.2.2 & Earlier

  • 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 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)

Acknowledgments

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.

Contributing

Contributions are welcome! Please submit pull requests or report issues through GitHub.

License

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.

Available Tools

8 tools
ask-codexC

Execute Codex CLI with file analysis (@syntax), model selection, and safety controls. Supports changeMode.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesTask or question. Use @ to include files (e.g., '@largefile.ts explain').
modelNoModel: gpt-5-codex, gpt-5, o3, o4-mini, codex-1, codex-mini-latest, gpt-4.1. Default: gpt-5-codex
sandboxNoQuick automation mode: enables workspace-write + on-failure approval. Alias for fullAuto.
fullAutoNoFull automation mode
approvalPolicyNoApproval: never, on-request, on-failure, untrusted
approvalNoApproval policy: untrusted, on-failure, on-request, never
sandboxModeNoAccess: read-only, workspace-write, danger-full-access
yoloNo⚠️ Bypass all safety (dangerous)
cdNoWorking directory
workingDirNoWorking directory for execution
changeModeNoReturn structured OLD/NEW edits for refactoring
chunkIndexNoChunk index (1-based)
chunkCacheKeyNoCache key for continuation
imageNoOptional image file path(s) to include with the prompt
configNoConfiguration overrides as 'key=value' string or object
profileNoConfiguration profile to use from ~/.codex/config.toml
timeoutNoMaximum execution time in milliseconds (optional)
includeThinkingNoInclude reasoning/thinking section in response
includeMetadataNoInclude configuration metadata in response
searchNoEnable web search by activating web_search_request feature flag. Requires network access - automatically sets sandbox to workspace-write if not specified.
ossNoUse local Ollama server (convenience for -c model_provider=oss). Requires Ollama running locally. Automatically sets sandbox to workspace-write if not specified.
enableFeaturesNoEnable feature flags (repeatable). Equivalent to -c features.<name>=true
disableFeaturesNoDisable feature flags (repeatable). Equivalent to -c features.<name>=false

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'safety controls' and 'changeMode' but doesn't explain what safety controls exist, what risks are involved, what permissions are needed, or what the tool actually does behaviorally. The description is too vague about execution behavior, error handling, or output format to be helpful for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently mentions key capabilities. It's appropriately sized for a complex tool, though it could be more front-loaded with the core purpose. There's no wasted verbiage, but the structure is basic without clear separation of concerns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 23 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, what kind of execution occurs, what safety considerations exist, or how it differs from sibling tools. The description fails to compensate for the lack of structured metadata about this significant CLI execution tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 23 parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions 'file analysis (@syntax), model selection, and safety controls' which correspond to some parameters, but doesn't provide additional semantic context or usage patterns. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool 'Execute Codex CLI with file analysis (@syntax), model selection, and safety controls. Supports changeMode.' This provides a general purpose (executing Codex CLI) with some features mentioned, but it's vague about what Codex CLI actually does and doesn't distinguish it from sibling tools like 'batch-codex' or 'brainstorm'. The description mentions capabilities but lacks specificity about the core function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. It doesn't mention when this tool is appropriate compared to 'batch-codex' (presumably for batch processing) or 'brainstorm' (presumably for ideation). There's no context about prerequisites, typical use cases, or exclusions for this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

batch-codexB

Delegate multiple atomic tasks to Codex for batch processing. Ideal for repetitive operations, mass refactoring, and automated code transformations

ParametersJSON Schema
NameRequiredDescriptionDefault
tasksYesArray of atomic tasks to delegate to Codex
modelNoModel to use: gpt-5-codex, gpt-5, o3, o4-mini, codex-1, codex-mini-latest, gpt-4.1
sandboxNoSandbox mode: read-only, workspace-write, danger-full-accessworkspace-write
parallelNoExecute tasks in parallel (experimental)
stopOnErrorNoStop execution if any task fails
timeoutNoMaximum execution time per task in milliseconds
workingDirNoWorking directory for execution
searchNoEnable web search for all tasks (activates web_search_request feature)
ossNoUse local Ollama server
enableFeaturesNoEnable feature flags
disableFeaturesNoDisable feature flags

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal details. It mentions 'batch processing' and use cases but doesn't describe critical behaviors like execution flow, error handling, output format, or resource implications. For a complex tool with 11 parameters and no annotations, this is inadequate, though not contradictory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences that efficiently convey purpose and ideal use cases. Every word earns its place without redundancy, and it's front-loaded with the core function. No unnecessary elaboration or waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, batch processing, no annotations, no output schema), the description is insufficient. It lacks details on execution behavior, result format, error handling, and integration with sibling tools. While concise, it doesn't provide enough context for an agent to fully understand how to invoke and interpret this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 11 parameters. The description adds no specific parameter details beyond implying tasks involve 'atomic' operations and targets use '@ syntax.' This meets the baseline of 3 since the schema does the heavy lifting, but the description doesn't enhance understanding of parameter interactions or semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Delegate multiple atomic tasks to Codex for batch processing' with specific use cases like 'repetitive operations, mass refactoring, and automated code transformations.' It distinguishes from sibling tools like 'ask-codex' by emphasizing batch processing rather than single interactions. However, it doesn't explicitly contrast with all siblings, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage context with 'Ideal for repetitive operations, mass refactoring, and automated code transformations,' which suggests when to use this tool. However, it lacks explicit guidance on when NOT to use it or clear alternatives among siblings like 'ask-codex' for single tasks. No prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brainstormC

Generate creative ideas using structured frameworks with domain context and feasibility analysis.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesBrainstorming challenge or question
modelNoModel: gpt-5-codex (default), gpt-5, o3, o4-mini, codex-1, codex-mini-latest, gpt-4.1
approvalPolicyNoApproval: never, on-request, on-failure, untrusted
sandboxModeNoAccess: read-only, workspace-write, danger-full-access
fullAutoNoFull automation mode
yoloNo⚠️ Bypass all safety (dangerous)
cdNoWorking directory
methodologyNoFramework: divergent, convergent, scamper, design-thinking, lateral, auto (default)auto
domainNoDomain: software, business, creative, research, product, marketing, etc.
constraintsNoLimitations: budget, time, technical, legal, etc.
existingContextNoBackground info or previous attempts
ideaCountNoNumber of ideas (default: 12, range: 5-30)
includeAnalysisNoInclude feasibility/impact analysis
searchNoEnable web search for research (activates web_search_request feature)
ossNoUse local Ollama server
enableFeaturesNoEnable feature flags
disableFeaturesNoDisable feature flags

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'feasibility analysis' but lacks critical details: it doesn't specify whether this is a read-only or mutating operation, what permissions or authentication might be required, potential rate limits, or output format. For a tool with 17 parameters and no annotations, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every phrase ('creative ideas', 'structured frameworks', 'domain context', 'feasibility analysis') contributes meaningfully, making it appropriately sized and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (17 parameters, no annotations, no output schema), the description is incomplete. It doesn't address behavioral aspects like safety, permissions, or output format, and while schema coverage is high, the description itself lacks depth to guide an agent in using such a multifaceted tool effectively. This is inadequate for a tool of this scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, meaning all parameters are documented in the schema itself. The description adds minimal value beyond the schema by hinting at 'structured frameworks' (related to 'methodology') and 'domain context' (related to 'domain'), but doesn't provide additional syntax, format, or usage details for parameters. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Generate creative ideas using structured frameworks with domain context and feasibility analysis.' It specifies the verb ('generate'), resource ('creative ideas'), and key aspects ('structured frameworks', 'domain context', 'feasibility analysis'). However, it doesn't explicitly differentiate from sibling tools like 'ask-codex' or 'batch-codex', which might also generate content, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. It doesn't mention sibling tools like 'ask-codex' or 'batch-codex', nor does it specify contexts or exclusions for usage. The agent must infer usage based on the purpose alone, which is insufficient for effective tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch-chunkA

Retrieves cached chunks from a changeMode response. Use this to get subsequent chunks after receiving a partial changeMode response.

ParametersJSON Schema
NameRequiredDescriptionDefault
cacheKeyYesThe cache key provided in the initial changeMode response
chunkIndexYesWhich chunk to retrieve (1-based index)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral burden. The word 'Retrieves' signals a read operation, and 'cached chunks' implies a non-destructive lookup from previously stored response data. It does not detail cache expiration or whether chunks can be re-fetched, but the core behavior 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences deliver the core behavior and the intended usage context with no wasted words. The primary action is front-loaded and the follow-up guidance is immediately actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives enough context for a simple two-parameter fetch tool: where the cacheKey comes from and when to call it. With no output schema, it could have clarified the response shape or chunk count, but the invocation path is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented. The description adds context about when the cacheKey/chunkIndex are used, but it does not provide substantial extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it retrieves cached chunks from a changeMode response. It also clarifies the tool's role as the follow-up mechanism for partial changeMode responses, making its purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use this tool 'after receiving a partial changeMode response' and positions it as the way to get subsequent chunks. It does not mention exclusions or alternatives, but no directly competing sibling tool is apparent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

HelpC

receive help information

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description should disclose behavior but only states the generic purpose; no details on side effects, permissions, or output are given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but lacks substance; it is not informative enough despite being concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description should provide more context (e.g., what help topics are covered), but it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%, meeting the baseline. The description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'receive help information' is vague and does not specify what kind of help or how it differs from sibling tools like ask-gemini.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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; no context or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pingC

Echo

ParametersJSON Schema
NameRequiredDescriptionDefault
promptNoMessage to echo

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Echo' only restates the core action and implies the prompt is returned, but it does not state side effects, safety traits, or response format. For a trivial tool this is minimally acceptable, but it still lacks explicit behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is extremely concise, it is under-specified rather than efficiently structured. A single word without context is not a well-formed definition, and the conciseness is the result of omission rather than careful pruning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's low complexity, the description leaves out important context such as the intended use (e.g., connectivity test or echo of user input) and the fact that the given prompt will be returned. There is no output schema, so the description should clarify return behavior, but it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage with the description 'Message to echo' for the prompt parameter. The description 'Echo' adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is a single word, 'Echo', which names an action but does not specify the resource or what is echoed. It is not a complete statement of purpose and leaves ambiguity about whether it echoes the prompt parameter or something else. This is more like a vague fragment than a clear tool definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 any of the sibling tools. There is no mention of typical use cases, prerequisites, or exclusions. An agent receives no context to decide whether to call ping instead of ask-gemini or brainstorm.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

timeout-testA

Test timeout prevention by running for a specified duration

ParametersJSON Schema
NameRequiredDescriptionDefault
durationYesDuration in milliseconds (minimum 10ms)

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states the tool runs for a specified duration but lacks details on side effects, return values, or whether it is read-only or destructive. This is insufficient for a tool that likely involves waiting or blocking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words. Every word contributes to the core message.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers the essential idea. However, it lacks context on what 'timeout prevention' means, typical use cases, and expected behavior after the duration elapses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (duration parameter already described). The description adds no additional meaning beyond 'running for a specified duration', which is already implied by the parameter name. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Test timeout prevention by running for a specified duration'. It uses a specific verb ('Test') and resource ('timeout prevention'), distinguishing it from sibling tools like 'ping' or 'health'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for testing timeout prevention but provides no explicit guidance on when to use this tool vs alternatives. No exclusions or when-not-to-use are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

versionA

Display version and system information

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updates
    • First observedask-codex
    • First observedbatch-codex
    • First observedbrainstorm
    • First observedfetch-chunk
    • First observedHelp
    • First observedping
    • First observedtimeout-test
    • First observedversion
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.7/5.0

Scored across 8 tools

Disambiguation3/5

Most tools have distinct purposes, but there is some overlap and ambiguity. For example, 'ask-codex' and 'batch-codex' both involve executing Codex CLI operations, which could cause confusion about when to use each. However, descriptions help clarify that 'batch-codex' is for multiple tasks, while 'ask-codex' is more general. Tools like 'brainstorm' and 'fetch-chunk' are clearly distinct, but the set includes basic utilities like 'ping' and 'Help' that don't align well with the code-focused domain.

Naming Consistency2/5

Naming conventions are inconsistent and chaotic with no discernible pattern. There is a mix of styles: 'ask-codex' and 'batch-codex' use hyphenated names, 'brainstorm' and 'fetch-chunk' are single words or hyphenated, 'Help' starts with a capital letter, and 'ping', 'timeout-test', and 'version' use different formats. This lack of consistency makes the tool set harder to navigate and predict.

Tool Count3/5

With 8 tools, the count is borderline but reasonable for the apparent scope of a Codex MCP server. However, the inclusion of basic utilities like 'ping', 'Help', and 'timeout-test' alongside core code tools feels slightly over-scoped, as these utilities don't directly contribute to the main purpose. It's not extreme, but the mix reduces focus.

Completeness3/5

The tool surface has notable gaps in coverage for the Codex domain. Core operations like code execution and batch processing are covered by 'ask-codex' and 'batch-codex', but there are missing operations such as code review, error handling, or integration with version control. Tools like 'brainstorm' and 'fetch-chunk' add niche functions, but the set lacks a cohesive lifecycle for code tasks, which could lead to agent workarounds.

Maintenance

ActivityInactive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Codex Bridge

    eLyiN
    A
    license
    A
    quality
    B
    maintenance
    Enables AI coding assistants to interact with OpenAI's Codex AI through the official CLI. Provides direct integration for code analysis, file review, and batch processing with zero API costs.
    3
    115
    MIT

  • codex-mcp-server

    tuannvm
    A
    license
    A
    quality
    C
    maintenance
    Bridges Claude and OpenAI's Codex CLI for AI-powered code analysis, generation, and review, with support for session management, web search, and structured output.
    6
    577 npm
    629
    ISC

  • codex-mcp

    anhnguyen0905
    A
    license
    A
    quality
    A
    maintenance
    Bridges Claude Code and OpenAI Codex CLI for an interactive plan-execute-review workflow, enabling Claude to interview, design, and review while Codex implements code changes.
    7
    424 npm
    3
    MIT

Appeared in Searches