This MCP server connects Claude/Cursor to the Codex CLI, enabling AI-powered coding tasks:
Ask Codex: Run one-off prompts with optional file references (@path), model selection, web search, sandbox controls, change mode (OLD/NEW patches), local OSS models (Ollama/LM Studio), and multi-turn session support.
Batch Codex: Run multiple tasks sequentially or in parallel with priorities, sandbox modes, and stop-on-error controls.
Review Changes: Run native code review on uncommitted changes, a specific commit, or against a base branch, with optional custom focus areas.
Do-Act: Execute a task, verify with a shell command, and automatically retry with fixes if verification fails.
Brainstorm: Generate ideas using frameworks like SCAMPER, design-thinking, or lateral thinking, including feasibility analysis and idea count controls.
Session Management: List, delete, or clear active multi-turn conversation sessions.
Skill Discovery: List available Codex skills from .agents/skills/ directories.
Health Diagnostics: Diagnose Codex CLI installation, version, features, and session health.
Change Chunk Retrieval: Fetch cached chunks from a previous change-mode response.
Local OSS Model Support: Run any tool against local Ollama or LM Studio models (e.g., qwen3:8b).
Safety & Controls: Fine-grained sandbox modes (read-only, workspace-write, danger-full-access), approval policies (never, on-request, untrusted), ephemeral runs, and configuration parameters like reasoning effort, timeout, and working directory.
Cross-Platform: Works on Windows, macOS, and Linux.
Utilities: Ping for connectivity, help for CLI usage, version output, and timeout test for debugging long requests.
Allows using local OSS models via Ollama as a provider for Codex tasks, enabling offline/local code analysis and generation.
Provides integration with OpenAI's Codex CLI, enabling AI agents to execute coding tasks, perform file analysis, run multi-turn sessions, sandboxed edits, and structured change-mode operations.
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-tool analyze @package.json and list dependencies"
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.
MCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via @ file references, multi-turn conversations, sandboxed edits, and structured change mode.
File Analysis — Reference files with @src/, @package.json syntax
Multi-Turn Sessions — Conversation continuity with workspace isolation
Native Resume — Uses codex resume for context preservation (CLI v0.36.0+)
Local OSS Models — Run with Ollama or LM Studio via localProvider
Web Search — Research capabilities with search: true
Sandbox Mode — Safe automation with explicit sandbox and approval policies
Change Mode — Structured OLD/NEW patch output for refactoring
Brainstorming — SCAMPER, design-thinking, lateral thinking frameworks
Health Diagnostics — CLI version, features, and session monitoring
Cross-Platform — Windows, macOS, Linux fully supported
Related MCP server: codex-mcp-server
claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-toolPrerequisites: Node.js 18+, Codex CLI installed and authenticated.
{
"mcpServers": {
"codex-cli": {
"command": "npx",
"args": ["-y", "@trishchuk/codex-mcp-tool"]
}
}
}Config locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json
// File analysis
'explain the architecture of @src/';
'analyze @package.json and list dependencies';
// With specific model
'use codex with model gpt-5.6-sol to analyze @algorithm.py';
// Multi-turn conversations (v1.4.0+)
'ask codex sessionId:"my-project" prompt:"explain @src/"';
'ask codex sessionId:"my-project" prompt:"now add error handling"';
// Brainstorming
'brainstorm ways to optimize CI/CD using SCAMPER method';
// Sandbox mode
'use codex sandbox:true to create and run a Python script';
// Web search
'ask codex search:true prompt:"latest TypeScript 5.7 features"';
// Local OSS model (Ollama)
'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"';Tool | Description |
| Execute Codex CLI with files, models, sessions, and safety controls |
| Run multiple atomic Codex tasks sequentially or concurrently |
| Run the native non-interactive Codex review command |
| Execute, verify with a shell command, and retry fixes |
| Generate ideas with structured creative frameworks |
| View, delete, or clear MCP conversation mappings |
| List skills visible from the selected workspace |
| Diagnose CLI installation, version, features, and sessions |
| Retrieve a chunk from cached change-mode output |
| Test the MCP connection |
| Return current |
| Report Codex CLI, Node.js, platform, and package versions |
| Exercise keepalive and timeout behavior |
By default the model parameter is omitted and Codex CLI applies the
default model from your ~/.codex/config.toml (for example model = "gpt-5.6-sol").
Pass model only when you need to override the configured default for a
single call. Reasoning depth is calibrated per tool:
ask-codex — uses the Codex CLI default reasoning (medium). Increase it only when the task needs more planning or checking.
brainstorm, do-act, review-changes — default reasoningEffort: "high" (creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).
Model | Recommendation |
| Most capable; complex, demanding, high-value work |
| Reliable agentic workhorse for everyday tasks |
| Balanced everyday coding with a better capability/cost |
| Clear, repeatable, high-volume tasks |
| Proven previous-generation fallback |
| Deprecated — Codex steers callers to |
GPT-6 Astra and GPT-5.6 Sol/Terra expose max and ultra reasoning; Luna tops
out at max. ultra may delegate work to subagents; most tasks should remain
on medium or high. Pass a concrete slug — the bare moving aliases gpt-6
and gpt-5.6 are rejected by the API.
Multi-turn conversations with workspace isolation:
{ "prompt": "analyze code", "sessionId": "my-session" }
{ "prompt": "continue from here", "sessionId": "my-session" }
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }Environment:
CODEX_SESSION_TTL_MS - Session TTL (default: 24h)
CODEX_MAX_SESSIONS - Max sessions (default: 50)
Requires Codex CLI 0.95.0 or newer. On older versions the server fails
with an explicit upgrade message rather than silently dropping unsupported
flags. Upgrade with npm install -g @openai/codex@latest; run the health tool
to see the detected version.
MCP clients launched from a GUI (Dock, Finder, Start menu) inherit a minimal
PATH that excludes Homebrew, nvm, and volta directories, so codex may work
from a terminal but not from the app. The server searches those locations
automatically; if it still cannot find the CLI, pin it explicitly:
{ "env": { "CODEX_CLI_PATH": "/opt/homebrew/bin/codex" } }Find the value with which codex. Run the health tool to see which
executable was resolved and how.
Run with local Ollama or LM Studio instead of OpenAI:
// Ollama
{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }
// LM Studio
{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }
// Auto-select provider
{ "prompt": "analyze @src/", "oss": true }Requirements: Ollama running locally with a model that supports tool calling (e.g. qwen3:8b).
Parameter | Description |
| Model selection |
| Enable conversation continuity |
| Compatibility automation: workspace-write + never |
| Enable web search |
| Structured OLD/NEW edits |
| Additional writable directories |
| Cap response verbosity (100-10,000) |
| low, medium, high, xhigh, max, ultra |
| Use local OSS model provider |
| Local provider: |
| Fail on unknown Codex configuration keys |
| Do not persist Codex session files |
| Ignore |
| Ignore execpolicy |
Validated against Codex CLI 0.144.3. The server keeps older feature guards,
but current releases are recommended. Notable current behavior:
--full-auto and approval policy on-failure have been removed by Codex CLI.
MCP sandbox: true / fullAuto: true remain compatibility aliases for
--sandbox workspace-write --ask-for-approval never; they do not bypass the sandbox.
Native --search is used without the deprecated web_search_request feature.
Current exec flags include --strict-config, --ephemeral,
--ignore-user-config, and --ignore-rules.
codex --version # Check CLI version
codex login # AuthenticateUse health tool for diagnostics: 'use health verbose:true'
v2.4.x → v2.5.0: Codex CLI 0.153.4 compatibility pass; added
gpt-6-astra. Breaking: dropped gpt-5.4 and the moving alias gpt-5.6
(both now rejected with HTTP 400), and removed the untrusted approval policy,
which Codex CLI 0.153.x no longer parses.
v2.3.x → v2.4.0: Codex CLI 0.144.3 compatibility audit; added GPT-5.6
Sol/Terra/Luna, max/ultra reasoning, current exec flags, native-only search,
and safe compatibility handling for the removed --full-auto flag and
on-failure approval policy.
v2.2.x → v2.3.0: gpt-5.5 as new default, added gpt-5.4-mini, dropped retired models (gpt-5.3-codex-spark, gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini).
v2.0.x → v2.1.0: gpt-5.4 as new default model, updated fallback chain.
v1.5.x → v1.6.0: Local OSS model support (localProvider, oss), gpt-5.3-codex default model, xhigh reasoning effort.
v1.3.x → v1.4.0: New sessionId parameter, list-sessions/health tools, structured error handling. No breaking changes.
MIT License. Not affiliated with OpenAI.
Documentation | Issues | Inspired by jamubc/gemini-mcp-tool
Generate creative ideas using structured frameworks with domain context and feasibility analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| cd | No | Working directory | |
| oss | No | Use local Ollama server | |
| yolo | No | ⚠️ Bypass all safety (dangerous) | |
| model | No | Optional model override. Known: gpt-5.6, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini. If omitted, uses your Codex CLI default (~/.codex/config.toml). | |
| domain | No | Domain: software, business, creative, research, product, marketing, etc. | |
| prompt | Yes | Brainstorming challenge or question | |
| search | No | Enable live web search using the native --search flag | |
| fullAuto | No | Compatibility alias for workspace-write with approval=never | |
| ideaCount | No | Number of ideas (default: 12, range: 5-30) | |
| constraints | No | Limitations: budget, time, technical, legal, etc. | |
| methodology | No | Framework: divergent, convergent, scamper, design-thinking, lateral, auto (default) | auto |
| personality | No | Communication style: pragmatic (concise, machine-friendly) or friendly (conversational). Codex CLI v0.94.0+ | |
| sandboxMode | No | Access: read-only, workspace-write, danger-full-access | |
| localProvider | No | Specify which local provider to use (lmstudio or ollama). Automatically enables --oss if not set. | |
| approvalPolicy | No | Approval: never, on-request, untrusted | |
| enableFeatures | No | Enable feature flags | |
| disableFeatures | No | Disable feature flags | |
| existingContext | No | Background info or previous attempts | |
| includeAnalysis | No | Include feasibility/impact analysis | |
| reasoningEffort | No | Reasoning depth. Default: high (creative ideation benefits from depth). Override with "xhigh" for very complex domains, "medium" for quick exploration. | high |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation) and openWorldHint=true (external resources). The description implies generation and analysis but does not detail behavioral traits like side effects, output format, or resource usage. No contradiction with 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 of 12 words, concise and front-loaded. It could benefit from structure but remains efficient. No wasted 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 tool's complexity (20 parameters, no output schema), the description is insufficient. It lacks information on return values, output format, and how results are presented. This gap is significant for an AI agent to correctly invoke and interpret 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% (all 20 parameters have descriptions). The tool description adds only implicit context about 'structured frameworks' and 'feasibility analysis' which maps to domain and includeAnalysis parameters. Baseline 3 is appropriate as schema handles most parameter semantics.
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 'Generate creative ideas using structured frameworks with domain context and feasibility analysis' clearly states the tool's purpose with specific verb, resource, and scope. It distinguishes from sibling tools which are utilities like ping, help, version, etc.
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 does not explicitly state when to use this tool versus alternatives. However, the sibling tools are sufficiently different (utilities), so an agent can infer context. Minimal guidance, no exclusions or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute task via Codex, verify with shell command, auto-fix on failure. Act-Check-Fix loop.
| Name | Required | Description | Default |
|---|---|---|---|
| oss | No | Use local Ollama/LM Studio | |
| task | Yes | Task for Codex to execute | |
| model | No | Optional model override. Known: gpt-5.6, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini. If omitted, uses your Codex CLI default (~/.codex/config.toml). | |
| verify | No | Shell command to validate result. Triggers act-check-fix loop on failure. | |
| timeout | No | Codex timeout per attempt in ms. Default: 10min | |
| fullAuto | No | Compatibility alias for workspace-write with approval=never | |
| maxRetries | No | Max retry attempts if verify fails. Default: 2 | |
| workingDir | No | Working directory | |
| sandboxMode | No | Access: read-only, workspace-write, danger-full-access | |
| localProvider | No | ||
| reasoningEffort | No | Reasoning depth. Default: high (act-check-fix loops benefit from depth so retries converge). Override with "xhigh" for hard tasks, "medium" for simple verifiable steps. | high |
| Name | Required | Description |
|---|---|---|
| steps | Yes | |
| status | Yes | |
| attempts | Yes | |
| durationMs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive and not read-only. The description adds behavioral context about the verification loop and auto-fixing, but does not elaborate on side effects beyond what annotations imply. No contradictions.
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, front-loading the core function. Every sentence adds value. Could be slightly more structured but is efficient overall.
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 11 parameters, a nested object, and an output schema, the description could provide more context about the loop's outcome or return format. However, the output schema covers return values, so the description is 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 high (91%), so the schema already documents most parameters. The description adds no additional meaning beyond the schema, such as clarifying the interplay between parameters. 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 clearly states the tool executes a task via Codex, verifies with a shell command, and auto-fixes on failure. It distinguishes itself from sibling tools that are primarily informational or have different purposes like 'brainstorm' or 'fetch-chunk'.
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 for tasks requiring verification and retry via 'Act-Check-Fix loop', but does not explicitly state when to use this tool over alternatives or when not to use it.
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?
The description adds no behavioral details beyond what the annotations already provide (readOnlyHint, idempotentHint). It does not specify any side effects or safety considerations, but annotations cover the read-only, idempotent nature.
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, front-loaded with the purpose. Every sentence adds value without redundancy. Highly concise and well-structured.
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 (2 params, no output schema), the description adequately covers what the tool does and when to use it. It could mention the return format or additional context about changeMode, but not strictly necessary.
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 schema fully documents both parameters. The description does not add any additional semantic meaning beyond naming the parameters, earning a baseline score of 3.
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 it retrieves cached chunks from a changeMode response, with specific verb and resource. It distinguishes from siblings (no other chunk retrieval tools) and states the context.
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 says 'Use this to get subsequent chunks after receiving a partial changeMode response', providing clear when-to-use guidance. However, it does not mention when not to use or provide alternatives, but given the tool's simplicity, this is sufficient.
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?
Annotations already mark the tool as read-only and idempotent, but the description adds no further behavioral details such as what information is returned or any side effects. It fails to add 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 phrase, but it is too vague to be considered appropriately concise. It lacks structure and fails to convey useful information efficiently.
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 absence of parameters and output schema, the description should still explain what 'help information' entails, but it does not. The tool's behavior is underspecified.
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, so the description cannot add parameter-level meaning. Baseline 4 applies as there is nothing to document.
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' is vague and does not specify what kind of help is provided, nor does it distinguish from sibling tools like 'list-skills' or 'ping'. It lacks a clear verb-resource structure.
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. There is no mention of context or prerequisites, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover available Codex skills from .agents/skills/ directory
| Name | Required | Description | Default |
|---|---|---|---|
| workingDir | No | Working directory to search for skills. Defaults to resolved working directory. |
| Name | Required | Description |
|---|---|---|
| skills | Yes | |
| baseDir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds the behavioral context that it searches the .agents/skills/ directory, beyond what annotations (readOnlyHint, idempotentHint) already provide. No contradictions; it's a simple read operation.
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, front-loaded with action and resource, no filler. 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?
For a simple, read-only tool with one optional parameter and an output schema (implied), the description is complete. It sufficiently covers what the tool does and its context.
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% with parameter 'workingDir' already described in the schema. The description does not add new semantic meaning beyond what the schema provides. Baseline 3 applies.
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 'Discover available Codex skills from .agents/skills/ directory' with a specific verb and resource. It distinguishes itself from siblings like ping, help, brainstorm, etc., which do not relate to skills discovery.
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 for discovering skills but does not provide explicit guidance on when to use this tool versus alternatives (e.g., other tools like brainstorm or fetch-chunk). No exclusions or context about when not to use it.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe. The description 'Echo' adds no new behavioral details and does not contradict annotations. It fails to add 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 one word, making it very concise. For a trivial tool, this level of brevity may be sufficient, but it could be slightly more informative. Nonetheless, it does not waste 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 tool's simplicity, low parameter count, and presence of annotations indicating safe operation, the single-word description is nearly complete. The output is implied as the echoed message. No output schema is needed. The description adequately conveys the tool's function.
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% and the parameter 'prompt' is described as 'Message to echo'. The description 'Echo' adds no extra semantic meaning. Baseline score of 3 is appropriate as schema already documents the parameter sufficiently.
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 returns the input, which is clear but minimal. It does not fully distinguish from sibling tools like 'timeout-test' or 'fetch-chunk', but the name 'ping' already implies a simple echo or test. The purpose is adequate but not highly specific.
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 'timeout-test' or 'do-act'. The description lacks context for choosing this tool over others.
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?
Annotations already indicate read-only, idempotent behavior. The description adds minimal extra context beyond the parameter, so it meets but does not exceed expectations.
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 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?
Given the tool's simplicity (one parameter, no output schema, safe annotations), the description is adequately complete. It could mention the return value, but that is not strictly necessary.
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 includes a description for the duration parameter. The tool description does not add additional meaning beyond what the schema provides.
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 tests timeout prevention by running for a specified duration. It is distinct from sibling tools like ping, help, etc.
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 such as ping or brainstorm. The description lacks context for appropriate usage.
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 | |||
| Name | Required | Description |
|---|---|---|
| nodeJs | Yes | |
| codexCli | No | |
| platform | Yes | |
| mcpServer | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnly/openWorld/idempotent hints, so the description adds minimal value beyond stating 'display' – no extra behavioral context like response format or side effects.
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, front-loaded with action and resource, no wasted 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?
With zero parameters, rich annotations, and existing output schema, the description covers necessary context fully.
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, so baseline is 4; description does not need to add param info.
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 it displays version and system information, distinguishing it from sibling tools like ping (connectivity) and help (documentation).
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 for checking version/system info but lacks explicit when-to-use, when-not-to-use, or alternatives beyond sibling names.
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.
v2.4.0brainstormdo-actfetch-chunkhelplist-skillspingtimeout-testversionScored across 8 tools
Each tool has a clearly distinct purpose: ping for echo, help for guidance, version for system info, brainstorm for idea generation, fetch-chunk for retrieving subsequent chunks, timeout-test for testing timeouts, list-skills for discovering skills, and do-act for task execution with verification. No overlapping purposes.
Tool names mix single words (ping, help, version, brainstorm) and hyphenated compounds (fetch-chunk, timeout-test, list-skills, do-act). While many follow a verb-noun pattern (fetch-chunk, list-skills, do-act), inconsistences like 'timeout-test' (noun-verb) and single-word names reduce overall coherence.
With 8 tools, the server is well-scoped for its purpose. Each tool earns its place by covering essential functionalities: basic info, brainstorming, workflow handling, testing, skill discovery, and task execution.
The tool set covers major areas: health check (ping), help, version, creativity (brainstorm), multi-step responses (fetch-chunk), timeout testing, skill discovery, and task execution (do-act). Minor gaps exist, such as a tool to list available modes or configure settings, but core workflows are supported.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
