Skip to main content
Glama
4dhxm

codex-mcp-server

by 4dhxm

Codex MCP Server

TypeScript MCP License

An open-source Model Context Protocol server that bridges MCP clients (Claude Desktop, Cursor, Poke, etc.) with the Codex CLI running on your machine.

Run coding tasks, manage conversation threads, fork sessions, and browse historical rolls — all through standard MCP tooling.

Prerequisites

  • Node.js 22+ (required for native SQLite bindings)

  • Codex CLI installed and authenticated — verify with codex doctor

Related MCP server: Codex Bridge MCP

Quick Start

git clone https://github.com/4dhxm/codex-mcp-server.git
cd codex-mcp-server
npm install
npm run build

Running the Server

1. Local Transport (stdio)

For MCP clients running on the same machine (like Claude Desktop or Cursor).

node dist/index.js

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "codex": {
      "command": "node",
      "args": ["/absolute/path/to/codex-mcp-server/dist/index.js"]
    }
  }
}

2. Remote Transport with Auto-Tunnel (Streamable HTTP + Cloudflare)

For exposing your local Codex installation to remote MCP clients (like Poke or a remote device) without dealing with routers or ngrok warning pages.

Dependency: You must have cloudflared installed. On macOS:

brew install cloudflared
node dist/index.js --http --tunnel

This starts the server and automatically spawns a free, highly-stable Cloudflare Quick Tunnel.

You can also explicitly set your API key:

node dist/index.js --http --tunnel --api-key my-secret-token

You will see output like this:

==============================================
🌐 Cloudflare tunnel established successfully!
Public URL: https://some-random-words.trycloudflare.com
MCP URL:    https://some-random-words.trycloudflare.com/mcp
==============================================

Connect from your remote MCP client:

URL:     https://some-random-words.trycloudflare.com/mcp
Type:    Streamable HTTP
Auth:    Bearer <your-api-key>

3. Local HTTP Network Transport

To run over HTTP without a public tunnel (for your local network):

node dist/index.js --http --port 8080

Authentication

API key auth is enabled by default for HTTP mode to protect your local machine from unauthorized remote access.

Provide a key via --api-key <key> flag or CODEX_MCP_API_KEY env var. If neither is set, a random secure key is generated and printed on startup.

How clients send the key — any of these work:

Method

Example

Authorization header

Authorization: Bearer sk-abc123

x-api-key header

x-api-key: sk-abc123

Query parameter

?apiKey=sk-abc123

The server intentionally avoids returning WWW-Authenticate headers to prevent MCP clients from attempting OAuth flows, ensuring simple Bearer token auth works cleanly.

Tools

Tool

Description

codex_task / codex_run

Run a coding task in a new thread

codex_start_thread

Initialize a thread without running a turn

codex_run_turn / codex_continue

Send a follow-up prompt to an existing thread

codex_list_threads

List active/archived threads from local SQLite

codex_get_thread

Get metadata and conversation history

codex_fork_thread

Clone a thread's history into a new session

codex_archive_thread

Archive a thread

codex_unarchive_thread

Unarchive a thread

codex_interrupt / codex_interrupt_turn

Abort a running turn

License

Apache 2.0

Available Tools

13 tools
codex_archive_threadB

Archive an active conversation thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe ID of the thread to archive.

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only states the action 'Archive' without explaining side effects, reversibility, or impact on ongoing conversations.

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, clear sentence with no redundant information. It is appropriately concise for a simple tool with one parameter.

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?

The tool lacks an output schema, and the description does not mention return values or success/error indications. It also omits any behavioral context (e.g., thread must be active) that would be necessary for complete understanding.

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 documents the threadId parameter with a description. The tool description adds no additional meaning beyond what the schema provides, so 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 uses the specific verb 'Archive' and the resource 'active conversation thread', clearly differentiating it from sibling tools like codex_unarchive_thread (opposite action) and codex_start_thread (creation).

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 such as codex_unarchive_thread. The description fails to indicate prerequisites or context for archiving.

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

codex_continueC

Alias for codex_run_turn. Continue an existing conversation thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
workingDirectoryNo
modelNo
sandboxModeNodanger-full-access
networkAccessEnabledNo
webSearchEnabledNo
threadIdYesThe ID of the thread to resume.
promptYesThe follow-up prompt or query.

TDQS

C2.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 carries full burden. It does not disclose behavioral traits like side effects (e.g., mutating the thread), permission requirements, rate limits, or whether it is safe. The alias note hints at behavior but is insufficient.

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 concise with two sentences, including an alias note. However, it could be slightly more structured or informative without losing brevity.

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 7 parameters, no output schema, and 12 sibling tools, the description is too brief. It omits details on return format, error handling, and the full scope of functionality, making it incomplete for confident agent invocation.

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

Parameters2/5

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

Only 29% of parameters have descriptions in the schema, and the description adds no information about any parameters. It does not explain workingDirectory, model, sandboxMode, etc., leaving agents to guess their meaning or rely on defaults.

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 states it continues an existing conversation thread and is an alias for codex_run_turn. This clearly identifies the tool's function and distinguishes it from siblings like codex_start_thread (start new) and codex_get_thread (view). However, it could be more specific about what 'continue' entails (e.g., adding a turn).

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 only mentions it is an alias for codex_run_turn, implying interchangeability, but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. With 12 sibling tools, more context is needed.

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

codex_continue_threadC

Alias for codex_run_turn. Continue a thread with a follow-up message.

ParametersJSON Schema
NameRequiredDescriptionDefault
workingDirectoryNo
modelNo
sandboxModeNodanger-full-access
networkAccessEnabledNo
webSearchEnabledNo
threadIdYesThe ID of the thread to resume.
promptYesThe follow-up prompt or query.

TDQS

C2.8/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It only states basic purpose and alias, with no mention of side effects, permissions, rate limits, or return behavior. Significant gap.

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 very short (two sentences). The first sentence about being an alias is arguably unnecessary and reduces conciseness. It is barely adequate but not overly verbose.

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 (7 parameters, no output schema, low schema coverage), the description fails to provide sufficient context. It does not explain what the tool returns, how other parameters affect behavior, or any interaction details.

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

Parameters2/5

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

Schema description coverage is only 29% (2 of 7 parameters have descriptions). The main description adds no extra parameter context. The existing descriptions for threadId and prompt are minimal and already in schema.

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 continues a thread with a follow-up message, but the 'alias for codex_run_turn' meta-statement is redundant and may confuse sibling differentiation. Purpose is clear but not outstanding.

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?

Usage is implied: use when you have an existing thread and want to add a message. However, no explicit when-not or alternatives are provided, despite having many sibling tools like codex_start_thread and codex_fork_thread.

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

codex_fork_threadB

Fork an existing thread into a new thread by cloning its session history.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe source thread ID to fork from.
cwdNoOptional working directory override for the new thread.

TDQS

B3.2/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 but only states the basic action. It does not disclose effects on the original thread, permissions needed, or whether the clone is deep or shallow. Minimal behavioral disclosure.

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 of 12 words, no fluff, directly states the core action. Front-loaded and efficient.

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?

No output schema exists, but description does not explain what the tool returns (e.g., new thread ID). Also missing context about thread existence requirement. Incomplete for a tool with no output schema.

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%, baseline 3. The description adds no additional meaning beyond the schema parameter descriptions, which are already clear. No further enrichment.

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 action (fork) and resource (thread) with the specific mechanism of cloning session history. It distinguishes from siblings like codex_start_thread (new thread) and codex_continue_thread (continuing existing).

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 such as codex_start_thread or codex_continue_thread. It does not mention prerequisites or context where forking is appropriate.

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

codex_get_threadA

Get metadata and full conversation history for a specific Codex thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe ID of the thread to retrieve.

TDQS

A3.6/5.0
Behavior3/5

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

No annotations exist, so description must carry behavioral context. It states the tool retrieves data, implying a read-only operation, but does not disclose any side effects, permissions needed, or return format 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?

Single sentence clearly states purpose with no unnecessary words. Highly concise and front-loaded.

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?

Tool is simple with one required parameter. Description appropriately informs the agent about retrieving full history. Could elaborate on response structure, but not essential given tool's straightforward nature.

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% and the description of threadId in the schema is adequate. The tool description adds no further meaning beyond what the schema provides.

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 specifies 'Get metadata and full conversation history for a specific Codex thread.' It clearly identifies the action (get) and resource (metadata and history), distinguishing it from siblings like codex_list_threads which lists all threads.

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 versus alternatives. Does not mention conditions like needing the full thread history or when to prefer codex_list_threads for a summary.

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

codex_interruptC

Alias for codex_interrupt_turn. Interrupt a running turn on an active thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe thread ID currently executing a turn.

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided; description only states it interrupts a running turn. Fails to disclose side effects, state changes, or irreversibility. Significant gap for a potentially destructive action.

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?

Extremely concise with no wasted words. Two sentences front-load the core purpose and alias relationship.

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?

Lacks output schema, behavioral details, and usage guidance. For a turn-interruption tool, missing critical context like whether it is reversible, any effects on thread state, or prerequisites.

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% for the single parameter (threadId). The description adds no additional semantic value beyond the schema, so baseline 3 applies.

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?

Clearly states it interrupts a running turn and notes it is an alias for codex_interrupt_turn. However, it does not differentiate from siblings; since it's an alias, purpose is clear but not uniquely distinguished.

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 versus alternatives. Merely states it's an alias without context on when interrupting a turn is appropriate or prerequisites.

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

codex_interrupt_turnB

Interrupt and abort the running turn or command on an active thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe thread ID currently executing a turn.

TDQS

B3.2/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. It states the action but omits details about side effects, required permissions, or thread state changes. The term 'abort' implies destructiveness but is not elaborated.

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 filler, directly states purpose. Efficient and front-loaded.

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 simple tool, the description is too brief. It does not mention return behavior, error conditions (e.g., what if thread not active), or any post-action state, leaving significant gaps despite tool simplicity.

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 of 'threadId'. The tool description adds no additional parameter information beyond the schema, so 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?

Description clearly states verb 'Interrupt and abort' and specific resource 'running turn or command on an active thread'. It differentiates from sibling 'codex_interrupt' by targeting a thread's turn/command specifically.

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 alternatives like 'codex_interrupt' or 'codex_fork_thread'. Does not mention prerequisites or conditions.

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

codex_list_threadsB

List historical and active Codex threads querying local session caches.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of threads to list.
includeArchivedNoWhether to include archived threads in the list.

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, so description bears full burden. It mentions caching but doesn't disclose staleness, latency, or whether it reflects real-time state. No side effects or auth requirements noted.

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?

Single sentence, no fluff. Could be slightly more informative without significant bloat, but current it's efficient.

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?

No output schema, but description doesn't hint at return format or contents (e.g., metadata vs full thread). Also lacks ordering or pagination details, leaving gaps for a simple list 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 baseline 3 applies. Description adds no parameter details beyond schema; the parameters are adequately described in 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 clearly states the verb 'List', the resource 'Codex threads', and the scope 'historical and active', with the method 'querying local session caches'. It distinguishes from siblings like codex_get_thread (singular) or codex_archive_thread.

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 versus siblings. For example, it doesn't mention that codex_get_thread retrieves a single thread or that codex_archive_thread pertains to archiving.

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

codex_runC

Alias for codex_task. Runs a task in a new Codex thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
workingDirectoryNo
modelNo
sandboxModeNodanger-full-access
networkAccessEnabledNo
webSearchEnabledNo
promptYesThe coding task or prompt for the Codex agent.

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, and the description only says 'Runs a task in a new Codex thread.' It does not disclose behavioral traits such as side effects, permissions, rate limits, or async nature, leaving agents uninformed.

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?

Two short sentences, no wasted words. However, the first sentence 'Alias for codex_task' adds minimal value and could be integrated.

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 6 parameters, no output schema, and no annotations, the description is highly incomplete. It lacks details on return values, error handling, and broader context for effective use.

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

Parameters2/5

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

With only 17% schema description coverage, the description adds no meaning to the six parameters. It does not explain sandboxMode, networkAccessEnabled, or other key parameters beyond the schema.

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?

States it's an alias for codex_task and runs a task in a new Codex thread, providing a clear verb and resource. However, it does not differentiate between codex_run and codex_task or other sibling tools like codex_start_thread.

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 versus alternatives like codex_task or codex_continue. The description merely states it's an alias without context.

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

codex_run_turnC

Run a follow-up turn or send a new prompt in an existing Codex thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
workingDirectoryNo
modelNo
sandboxModeNodanger-full-access
networkAccessEnabledNo
webSearchEnabledNo
threadIdYesThe ID of the thread to resume.
promptYesThe follow-up prompt or query for the agent.

TDQS

C2.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 carries full burden. It does not disclose behavioral traits such as side effects on thread state, required permissions, or whether the operation is destructive. The agent lacks critical information about safety.

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 clear sentence, front-loaded with the verb 'run'. It is concise but could be expanded slightly for better completeness without losing efficiency.

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 has 7 parameters, no output schema, and no annotations, the description is far from complete. It does not explain return values, prerequisites, or how the thread state changes. The agent lacks sufficient context to use the tool correctly.

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

Parameters2/5

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

With only 29% schema description coverage, the description adds no additional meaning beyond the schema. It does not explain the purpose or constraints of parameters like workingDirectory, model, or networkAccessEnabled, leaving the agent to guess.

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 runs a follow-up turn or sends a new prompt in an existing thread, using specific verbs and resources. However, it does not differentiate from sibling tools like codex_continue or codex_continue_thread, which likely have similar purposes.

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, nor does it mention prerequisites or exclusions. The agent must infer usage from context.

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

codex_start_threadC

Start a new conversation thread session with the Codex agent.

ParametersJSON Schema
NameRequiredDescriptionDefault
workingDirectoryNo
modelNo
sandboxModeNodanger-full-access
networkAccessEnabledNo
webSearchEnabledNo

TDQS

C2.3/5.0
Behavior1/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 but only states purpose. It fails to mention side effects, requirements, or session lifecycle details, leaving the agent uninformed about important behavioral traits.

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 concise sentence with no waste, but its brevity sacrifices necessary detail. It is appropriately structured and front-loaded, though overly minimal.

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

Completeness1/5

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

Given the tool has five parameters, no output schema, and no annotations, the description is highly incomplete. It does not cover parameter details, behavioral context, or usage guidance, leaving significant gaps for correct invocation.

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

Parameters1/5

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

The description provides zero information about the five parameters despite 0% schema description coverage. Parameters like workingDirectory, model, and sandboxMode are undefined, so the agent cannot infer their meaning or usage.

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 starts a new conversation thread session, which is a specific action and resource. The name 'codex_start_thread' further clarifies, distinguishing it from siblings like 'codex_continue_thread' or 'codex_fork_thread'.

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 such as codex_continue or codex_run. The description lacks context for selecting this tool among siblings.

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

codex_taskC

Run an autonomous coding task in a new Codex thread and return the final response.

ParametersJSON Schema
NameRequiredDescriptionDefault
workingDirectoryNo
modelNo
sandboxModeNodanger-full-access
networkAccessEnabledNo
webSearchEnabledNo
promptYesThe coding task or prompt for the Codex agent.

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It mentions returning a final response but does not detail side effects like file modifications, sandbox mode implications, network access, or potential long execution times. The term 'autonomous' hints at self-direction but leaves many behavioral aspects unclear.

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?

The description is a single sentence, which is concise but lacks necessary detail. For a tool with six parameters and no annotations, the description should include more information to be useful. It is under-specified rather than efficiently comprehensive.

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

Completeness1/5

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

Given the tool's complexity (6 parameters, no output schema, no annotations), the description is severely incomplete. It fails to explain parameter semantics, sandbox modes, or thread lifecycle. The single sentence does not provide enough context for correct tool invocation.

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

Parameters2/5

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

Schema description coverage is only 17% (only 'prompt' has a description). The tool description adds no additional meaning to parameters; it does not explain workingDirectory, model, sandboxMode, networkAccessEnabled, or webSearchEnabled. The description does not compensate for the low schema coverage.

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 it runs an autonomous coding task in a new Codex thread and returns the final response. The verb 'run' and the resource 'autonomous coding task in a new Codex thread' are specific, and the tool is differentiated from siblings like codex_run or codex_continue by explicitly mentioning 'new Codex thread'.

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 does not explicitly state when to use this tool versus alternatives. However, the phrase 'in a new Codex thread' implies it is for starting a fresh task, which provides some implicit guidance. No exclusions or when-not-to-use cases are mentioned.

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

codex_unarchive_threadB

Unarchive a previously archived conversation thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
threadIdYesThe ID of the thread to unarchive.

TDQS

B3.3/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. It only states the basic action (unarchive) without disclosing effects, idempotency, error states, or what happens when unarchiving an already unarchived thread. This is insufficient for 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.

Conciseness4/5

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

The description is a single, clear sentence that is front-loaded and efficient. However, it lacks detail, which is penalized elsewhere. For conciseness alone, it is good.

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?

The tool has one required parameter and no output schema. The description minimally explains the purpose but omits context like preconditions (thread must be archived), error conditions, or post-unarchive state. It is incomplete for an agent to use correctly without additional assumptions.

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 one parameter (threadId) already described. The description adds no additional meaning beyond the schema's own description. 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 'Unarchive a previously archived conversation thread' uses the specific verb 'Unarchive' and identifies the resource 'thread'. The name itself is clear, and it distinguishes from sibling tools like codex_archive_thread (opposite) and codex_get_thread (read-only).

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 the tool is used when a user wants to restore an archived thread, but it does not explicitly state when to use it versus alternatives. No guidance on prerequisites or when not to use is provided.

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. 13 tool updatesv2.0.0
    • First observedcodex_archive_thread
    • First observedcodex_continue
    • First observedcodex_continue_thread
    • First observedcodex_fork_thread
    • First observedcodex_get_thread
    • First observedcodex_interrupt
    • First observedcodex_interrupt_turn
    • First observedcodex_list_threads
    • First observedcodex_run
    • First observedcodex_run_turn
    • First observedcodex_start_thread
    • First observedcodex_task
    • First observedcodex_unarchive_thread

TDQS

C2.9/5.0
Disambiguation2/5

Several tools have overlapping purposes, such as codex_continue, codex_continue_thread, and codex_run_turn all appearing to continue a thread. Aliases like codex_continue and codex_interrupt add confusion, making it hard for an agent to select the correct tool.

Naming Consistency3/5

The snake_case and 'codex_' prefix are consistent, but the presence of aliases (e.g., codex_continue vs. codex_continue_thread) and inconsistent verb usage (run, continue, fork, archive) reduces clarity.

Tool Count4/5

13 tools is a reasonable number for managing Codex threads, covering creation, continuation, interruption, archiving, and listing. It is well-scoped without being excessive.

Completeness4/5

The tool set covers essential thread operations: start, continue, fork, archive, unarchive, list, and get. Missing update/delete capabilities are minor given the conversational domain, and most workflows are supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

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/4dhxm/codex-mcp-server'

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