Skip to main content
Glama
TKasperczyk

codex-mcp-swarm

by TKasperczyk

codex-mcp-swarm

An MCP server that wraps OpenAI's Codex CLI with true parallel execution and live task monitoring. Zero dependencies -- single Python file, stdlib only.

Why?

The official codex mcp-server processes requests sequentially. If your MCP client (Claude Code, etc.) needs to run 5 Codex tasks, they queue up one after another. This server spawns each task as an independent subprocess, so they run in parallel.

Unique features no other Codex MCP wrapper has:

  • Worktree isolation -- worktree: true creates an isolated git worktree per task so parallel Codex instances never edit past each other

  • Batch wait -- launch N tasks, call codex_wait once, get all results when they finish

  • Live status -- see what each Codex task is doing right now (last tool call, current reasoning, progress)

  • Full flag parity -- same parameters as the official Codex MCP tool (sandbox, approval-policy, cwd, model, config, etc.)

  • Drop-in config -- accepts the same -c key=value server args as codex mcp-server

Related MCP server: switchyard

Tools

Tool

Description

codex

Synchronous execution (drop-in replacement for official); terminal failures include the model, structured cause, category, and retryability

codex_async

Launch a task, get a task_id immediately (fan-out). Not fire-and-forget: results come back only via codex_wait. Pass threadId to resume a session

codex_reply

Continue a previous session via codex exec resume; uses the same structured failure reporting as codex

codex_status

Live view: tools called, last command, current thinking, warnings, and terminal failure cause

codex_wait

Block until multiple tasks complete and return results or structured failure details

codex_cancel

Kill a running async task (preserves worktree for inspection); if it already failed, return the recorded cause

Installation

Claude Code

claude mcp add codex-swarm -- uvx --upgrade codex-mcp-swarm \
  -c model=gpt-6-astra \
  -c approval_policy=never \
  -c sandbox_mode=danger-full-access \
  --skip-git-repo-check

That's it. No clone, no setup. uvx downloads and runs it directly from PyPI. The --upgrade flag ensures you always get the latest version on restart.

Note: Requires uv (curl -LsSf https://astral.sh/uv/install.sh | sh). Alternatively, use pipx run codex-mcp-swarm instead of uvx codex-mcp-swarm.

Manual (~/.claude.json)

{
  "mcpServers": {
    "codex-swarm": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--upgrade",
        "codex-mcp-swarm",
        "-c", "model=gpt-6-astra",
        "-c", "approval_policy=never",
        "-c", "sandbox_mode=danger-full-access",
        "--skip-git-repo-check"
      ]
    }
  }
}

The -c flags are identical to codex mcp-server -- copy-paste your existing config.

Usage

Parallel execution

1. Call codex_async with prompt A  -->  task_id: "abc123"
2. Call codex_async with prompt B  -->  task_id: "def456"
3. Call codex_async with prompt C  -->  task_id: "ghi789"
4. Call codex_wait(task_ids=["abc123", "def456", "ghi789"])
   --> blocks until all finish, returns all results

Collecting results: read this before you fan out

A task_id is internal to this server. Your MCP client does not track it. It will not appear in a task list, and no notification fires when the task finishes. If the agent's turn ends before codex_wait is called, the Codex run still completes and writes its result to disk, but nothing is left to deliver it and nothing wakes the session. codex_status is a progress peek only; it collects nothing.

So: codex_async and codex_wait belong in the same turn.

Let the wait run long. Claude Code moves any main-conversation tool call still running after two minutes into a tracked background task and re-invokes the session with the result when it settles -- that is the wake-up mechanism, so crossing the two-minute line is the goal rather than something to dodge. Short timeout values are raised to a floor (default 150s, override with CODEX_SWARM_MIN_WAIT) for exactly this reason. Tasks that have already finished return instantly regardless of the floor.

Failure reporting and terminal precedence

codex exec writes progress, warnings and sandbox notices to stderr on perfectly healthy runs. Until 1.10.0, a task whose exit code was lost to a reaping race was marked failed on the strength of non-empty stderr alone, so finished work got reported as a failure and callers acted on it.

Version 1.11.0 uses the terminal events in codex exec --json as the primary lifecycle signal. An unambiguous turn.completed means success even if an earlier top-level error event was emitted while the CLI retried. An unambiguous turn.failed means failure even if an earlier, partial agent_message exists. Top-level error events are diagnostic rather than terminal, because the public JSONL omits the CLI's internal will_retry field; item.completed events whose item type is error are warnings. If terminal events are absent or contradict each other, an observed process exit code decides the result. Only a verdict made without either signal is marked as inferred, and both completion and failure outputs label that explicitly.

Terminal failures report the model parsed from the command that actually ran, the structured turn.failed.error.message, a failure category, whether a later retry is likely to be useful, and a suggested action. Retryability is information only: the wrapper never starts a second Codex turn. The Codex CLI may perform its own in-turn retries. Stderr can be included as a clearly labeled, truncated diagnostics section, but it never replaces the primary failure cause.

Two things follow for anyone consuming this server:

  • A FAILED from codex_status or codex_wait that is flagged as inferred is a prompt to verify, not a conclusion. Check pgrep -af 'codex exec', file mtimes, the worktree branch, and your own build or tests.

  • A codex_wait that times out is not a failure at all. The task is not killed. Call codex_wait again with the same task_id.

Worktree isolation

Prevent parallel tasks from editing the same files:

1. Call codex_async(prompt="Refactor auth", worktree=true)
   --> task_id: "abc123"
   --> Worktree Branch: codex-swarm/abc123

2. Call codex_async(prompt="Add logging", worktree=true)
   --> task_id: "def456"
   --> Worktree Branch: codex-swarm/def456

3. codex_wait(task_ids=["abc123", "def456"])
4. git merge codex-swarm/abc123
5. git merge codex-swarm/def456

Each task gets its own git worktree and branch based on HEAD. After completion, merge the branches back. Worktrees are automatically cleaned up after 24 hours (configurable via CODEX_SWARM_TASK_MAX_AGE).

Live monitoring

Call codex_status(task_ids=["abc123"])
-->
=== Task abc123 (45s elapsed) ===
Phase: running
Tools called: 23
Last tool: exec_command(grep -rn "handleError" src/)
Output: Analyzing error handling patterns across the codebase...

Session continuity

1. Call codex(prompt="Review this file")  -->  result + session persisted
2. Call codex_reply(threadId="<session-uuid>", prompt="Now fix the bug you found")

For a follow-up that will run more than a few minutes, resume in the background instead -- codex_async accepts threadId and gives you a task_id that survives a client idle timeout:

1. Call codex_async(threadId="<session-uuid>", prompt="Now implement it")
                                          -->  task_id: "abc123"
2. Call codex_wait(task_ids=["abc123"])   -->  result, with full prior context

codex_reply is synchronous and emits progress notifications while it waits, but a client that gives up on silence will still abandon the request. Only the async path leaves you a handle to recover with.

Server flags

Flag

Description

-c key=value

Config default (repeatable). Same format as codex mcp-server.

--skip-git-repo-check

Allow running outside git repos.

--ephemeral

Don't persist session files. Disables codex_reply.

Per-call parameters

All parameters from the official Codex MCP tool are supported:

  • prompt (required)

  • model -- override server default

  • sandbox -- read-only, workspace-write, danger-full-access

  • approval-policy -- untrusted, on-failure, on-request, never

  • cwd -- working directory

  • profile -- config profile from config.toml (ignored on threadId resumes -- codex exec resume has no --profile flag)

  • config -- object of key=value overrides

  • worktree -- run in an isolated git worktree (prevents parallel tasks from conflicting)

  • base-instructions, developer-instructions, compact-prompt

MCP Resources

The server exposes read-only resources for discoverability:

URI

Description

codex-swarm:///server-info

Version, capabilities, directories, config

codex-swarm:///config

Current server-level defaults and flags

codex-swarm:///tasks

All known tasks and their current state; failed entries include model, cause, category, and retryability

Environment variables

Variable

Default

Description

CODEX_SWARM_LOG

/tmp/codex_mcp_swarm.log

Log file path

CODEX_SWARM_LOG_LEVEL

WARNING

Log level (DEBUG, INFO, WARNING, ERROR)

CODEX_SWARM_TASK_DIR

/tmp/codex_swarm_tasks

Task output storage directory

CODEX_SWARM_WORKTREE_DIR

/tmp/codex-swarm-worktrees

Worktree storage directory

CODEX_SWARM_TASK_MAX_AGE

86400 (24h)

Seconds before completed task artifacts (and worktrees) are cleaned up

CODEX_SWARM_MIN_WAIT

150

Floor in seconds for codex_wait. Keeps the call above the client's 2-minute auto-backgrounding threshold so completion re-invokes the session. Already-finished tasks ignore it

Requirements

  • Python 3.8+

  • Codex CLI installed and authenticated

  • No pip dependencies (stdlib only)

  • Works on Linux and macOS (Linux gets extra PID reuse protection and zombie detection via /proc)

Credits

Originally inspired by jeanchristophe13v/codex-mcp-async. Rewritten with full flag parity, JSONL status parsing, batch wait, and session reply support.

License

MIT

Available Tools

6 tools
codexB

Run a Codex session synchronously. Parameters match the official Codex MCP tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe initial user prompt for the Codex session.
approval-policyNoApproval policy for shell commands generated by the model.
sandboxNoSandbox mode.
cwdNoWorking directory for the session. If relative, resolved against the server's cwd.
worktreeNoCreate an isolated git worktree and branch for this task. Each task gets its own copy of the repo so parallel tasks never conflict. The response includes the branch name (codex-swarm/<task_id>) -- merge it back when done.
modelNoOptional override for the model name (e.g. 'gpt-5.4').
profileNoConfiguration profile from config.toml.
configNoConfig settings that override server defaults.
base-instructionsNoInstructions to use instead of the defaults.
developer-instructionsNoDeveloper instructions injected as developer role message.
compact-promptNoPrompt used when compacting the conversation.

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral disclosure. It only says 'synchronously', omitting details like blocking, duration, side effects (sandbox, worktree creation), or return value. This is insufficient for safe invocation.

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, front-loaded sentence that efficiently states the core purpose. It is appropriately concise, though could be slightly more specific.

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 11 parameters, no output schema, and no annotations, the description is too minimal. It fails to explain what a Codex session does, what it returns, or important behaviors (e.g., it may take time, creates worktrees).

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 coverage is 100%, so baseline is 3. The description adds no additional meaning beyond what the schema already provides. The phrase 'Parameters match the official Codex MCP tool' is generic and not helpful.

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 it runs a Codex session synchronously, which is a specific verb+resource. It implicitly differentiates from siblings like codex_async by mentioning 'synchronously', but does not explicitly name alternatives.

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 no explicit when-to-use guidance. It implies synchronous execution, but does not contrast with async or other management tools. Agents are left to infer usage from the tool name.

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

codex_asyncA

Start a Codex task in the background and return immediately with a task_id. Use codex_wait to collect results from one or more tasks, or codex_status to monitor progress. Set worktree=true to isolate each task in its own git worktree so parallel tasks don't conflict -- merge the branch back when done.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe initial user prompt for the Codex session.
approval-policyNoApproval policy for shell commands generated by the model.
sandboxNoSandbox mode.
cwdNoWorking directory for the session. If relative, resolved against the server's cwd.
worktreeNoCreate an isolated git worktree and branch for this task. Each task gets its own copy of the repo so parallel tasks never conflict. The response includes the branch name (codex-swarm/<task_id>) -- merge it back when done.
modelNoOptional override for the model name (e.g. 'gpt-5.4').
profileNoConfiguration profile from config.toml.
configNoConfig settings that override server defaults.
base-instructionsNoInstructions to use instead of the defaults.
developer-instructionsNoDeveloper instructions injected as developer role message.
compact-promptNoPrompt used when compacting the conversation.

TDQS

A4.4/5.0
Behavior4/5

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

No annotations exist, so the description carries full burden. It transparently explains the async behavior, immediate return, and worktree isolation. However, it does not disclose potential side effects, authorization needs, or task persistence, which are minor gaps.

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 three sentences, each adding distinct value. The main action is front-loaded, and every sentence earns its place without unnecessary words.

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?

Given the tool's complexity (11 parameters, async workflow), the description covers the key workflow: start, get task_id, use companion tools. It lacks details on return format and error conditions, but is otherwise complete for a background task 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the worktree parameter's behavior and purpose, but does not enhance understanding of other parameters beyond their schema descriptions.

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 starts a Codex task in the background and returns a task_id immediately. It distinguishes itself from siblings by referencing codex_wait and codex_status for collecting results and monitoring progress.

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

Usage Guidelines5/5

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

Explicitly guides when to use: for background task execution. Mentions alternatives (codex_wait, codex_status) and provides context for using the worktree parameter to avoid conflicts in parallel tasks.

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

codex_cancelA

Kill a running async Codex task. The process is terminated and the task is marked as cancelled. Any worktree and partial output are preserved for inspection.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYesThe task_id to cancel.

TDQS

A4.1/5.0
Behavior4/5

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

No annotations provided; description carries full burden. It discloses that the process is terminated, task marked cancelled, and worktree/partial output preserved. This is good but lacks mentions of permissions or irreversible effects.

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 concise sentences, front-loaded with the action. Every word serves a purpose; no wasted text.

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

Completeness5/5

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

Given the tool's low complexity (1 parameter, no output schema), the description provides sufficient behavioral and side-effect information to understand the tool's function.

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 coverage is 100%, so description adds minimal value beyond the schema description. It basically restates the parameter's purpose without additional details on format or constraints.

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?

Description clearly states the action (kill/cancel) and resource (async Codex task). It distinguishes from siblings like codex_async (starts tasks) and codex_status (checks status).

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?

Description implies usage for canceling a running task but provides no explicit guidance on when to use versus alternatives 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.

codex_replyA

Continue a Codex conversation by providing the thread/session ID and a follow-up prompt. Uses codex exec resume under the hood.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe session/thread ID (UUID) from a previous Codex call.
promptYesThe follow-up prompt to continue the conversation.

TDQS

A3.7/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. It mentions using 'codex exec resume' under the hood, but does not disclose whether the tool is blocking, error handling, or rate limits. This is minimal behavioral disclosure for a continuation tool.

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 sentence plus a brief technical note. It is front-loaded with the core purpose, no wasted words, and efficient for agent consumption.

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?

Given the tool's simplicity (2 required params, no output schema), the description is minimally viable. It explains the action and underlying command but lacks usage guidelines and behavioral details. Could be more complete with usage context.

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 both parameters thoroughly. The description adds no new meaning beyond restating the parameter roles. 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 purpose: 'Continue a Codex conversation' by providing a thread ID and prompt. It distinguishes from sibling tools like 'codex' (which likely starts new conversations) and async variants, making it easy for an agent to select appropriately.

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 implies use when continuing an existing conversation, and the sibling list provides context. However, it lacks explicit 'when to use' vs. alternatives, such as preferring 'codex' for new sessions. Still, the guidance is clear for most scenarios.

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

codex_statusA

Get live status of running async Codex tasks. Shows what each task is currently doing: last tool call, reasoning, progress. Works on both running and completed tasks.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idsYesList of task_ids to check status for.

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It discloses the tool is for live status (no side effects) and specifies what information it provides. It could mention polling behavior or rate limits, but the transparency is adequate for a read-only status check.

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 two sentences long, front-loaded with the main action, and contains no fluff. Every sentence provides useful information.

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 tool is simple (1 param, no output schema). The description covers functionality and output details. It omits the exact output format, but given no output schema, this is acceptable. Overall complete for the tool's complexity.

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 coverage is 100% with a clear description for task_ids. The description does not add extra meaning beyond the schema, but baseline 3 is appropriate since the schema already documents the parameter adequately.

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 retrieves live status of async Codex tasks, specifying what information it shows (last tool call, reasoning, progress). It differentiates from siblings like codex_async (starts tasks) and codex_cancel (cancels them).

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 implies usage after starting an async task with codex_async and notes it works on both running and completed tasks. It does not explicitly exclude use cases or state alternatives, but context from sibling names provides enough guidance.

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

codex_waitA

Block until one or more async Codex tasks complete, then return all results. Accepts a list of task_ids. This avoids repeated polling -- call once after launching codex_async tasks. Default timeout is 1800s (30 min). If a task times out, it is NOT killed -- it keeps running. You can call codex_wait again with the same task_ids to resume waiting, or use codex_status to check progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idsYesList of task_ids to wait for.
timeoutNoMax seconds to wait (default: 1800). The task keeps running even if this times out.

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations provided, the description bears full responsibility for behavioral disclosure. It clearly states the tool blocks, has a default timeout of 1800s, and that timed-out tasks continue running. This covers the key behaviors without omitting critical details.

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: two sentences plus a timeout note. It immediately states the purpose and provides necessary usage context without superfluous words.

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

Completeness5/5

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

Given the absence of an output schema and the tool's simplicity (two parameters), the description covers all essential aspects: purpose, when to use, timeout behavior, and follow-up options. It is complete for effective tool selection and invocation.

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 coverage for parameters is 100%, with descriptions already present. The tool description adds context about default timeout and non-killing behavior, but this is also captured in the schema's timeout description. Thus, parameter semantics are adequate but not significantly enhanced 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 explicitly states 'Block until one or more async Codex tasks complete, then return all results.' It distinguishes from siblings like codex_status and codex_async by noting that it avoids polling and contrasts with launching tasks.

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

Usage Guidelines5/5

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

The description advises to 'call once after launching codex_async tasks' and explains timeout behavior: 'If a task times out, it is NOT killed -- it keeps running. You can call codex_wait again... or use codex_status to check progress.' This provides clear guidance on when and how to use the tool.

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. Dates show when Glama detected each change.

  1. 6 tool updatesv1.7.0
    • First observedcodex
    • First observedcodex_async
    • First observedcodex_cancel
    • First observedcodex_reply
    • First observedcodex_status
    • First observedcodex_wait

TDQS

A3.9/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: sync execution, async launch, cancel, reply, status polling, and waiting. No two tools overlap in functionality.

Naming Consistency4/5

Most tools follow the 'codex_' prefix with a clear verb, but the sync tool is simply 'codex' without an underscore, creating a minor inconsistency.

Tool Count5/5

6 tools is appropriate for managing Codex sessions, covering sync and async operations, cancellation, continuation, status, and blocking wait.

Completeness4/5

Core lifecycle is well-covered (start, wait, cancel, continue, monitor). Minor gap: no tool to list all active tasks, though status can query known task IDs.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/TKasperczyk/codex-mcp-swarm'

If you have feedback or need assistance with the MCP directory API, please join our Discord server