codex-mcp

by anhnguyen0905

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.25.0
Disambiguation5/5
Each tool has a clearly distinct purpose: discovering sessions, executing new tasks, resuming sessions, reviewing changes, batching work, reading metrics, and checking health. Though execute and batch both run Codex, their scope (single vs. fanned-out) is explicit and easy to distinguish.
Naming Consistency4/5
All tools share the consistent codex_ prefix and snake_case style, which makes them predictable. However, the suffix mixes verbs (execute, continue) with nouns (sessions, metrics, batch, health), so it is not a strict verb_noun convention.
Tool Count5/5
Seven tools is well-scoped for a Codex-focused server. Each tool covers a meaningful workflow: session discovery, execution, continuation, review, batch processing, metrics, and health checks, with no obvious bloat.
Completeness4/5
The set covers the core Codex lifecycle: create and run sessions, resume them, review changes, batch tasks, and observe usage/health. Minor gaps exist, such as no explicit tool for full session transcripts or canceling in-progress sessions, but agents can work around these using returned sessionIds and the CLI.
Average 4/5 across 7 of 7 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 129 commits in the last 12 weeks
- Last stable release on September 8, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It mentions that the tool runs a task and returns file changes and commands run, which implies workspace mutation, but it does not state the default sandbox policy, potential side effects, or that this is an execution tool capable of modifying files. This is a significant gap for a code-execution 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 focused sentence that front-loads the primary action, states the workspace scope, and lists meaningful return artifacts. There is no redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 10-parameter execution tool with no annotations, the description is somewhat thin. It explains the core function and key return values, and the output schema covers return structure, but it omits safety-critical context such as the default sandbox being workspace-write and the existence of verification behavior. The description is adequate for basic selection but not fully complete for safe invocation without reading every schema field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all ten parameters. The description does not add deeper parameter semantics, though mentioning sessionId as something to keep for later review provides mild context about the session lifecycle. This matches the baseline for high 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 uses a specific verb and resource: 'Start a new Codex session that executes a plan/task in the given workspace.' It clearly identifies the tool as a session-starter and executor, and the mention of 'new' helps distinguish it from sibling tools like codex_continue. The return values are also summarized, so an agent can tell what to expect.
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 this tool is for starting a fresh execution rather than continuing or reviewing an existing session, but it does not explicitly name alternatives or state when not to use it. Sibling tools like codex_continue and codex_review are not referenced, leaving the agent to infer routing from the word 'new.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that the session is resumed and context preserved; it does not mention that Codex may execute in a mutable workspace, run verification commands, open a terminal, or persist notes. These are significant side effects for a code-execution tool and are not surfaced in the prose description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler: the action, target, and context-preserving benefit are all front-loaded. The description earns each word and is easy to scan.
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 complex (11 parameters, code execution), but the schema describes every parameter and an output schema exists, so the description is not required to restate details. It supplies the missing high-level purpose and typical usage. It stops short of full completeness because it omits safety/behavioral context that an annotation-lacking execution tool would benefit from, though the schema partially compensates.
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 meaningful descriptions for all 11 parameters, so the baseline is 3. The description adds only that the prompt is typically review feedback, which largely restates the schema's example for prompt. No additional parameter-level meaning is provided.
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 opens with a specific verb and resource: 'Resume an existing Codex session by sessionId with a follow-up prompt'. It also adds the key differentiator 'Preserves Codex context', which separates it from starting a new session. It does not explicitly name sibling tools, but the purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete use case: 'typically review feedback that Codex should address', so an agent knows when continuing is appropriate. It does not explicitly contrast with codex_execute or codex_review, nor state when not to use this tool, so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full behavioral burden and does disclose the data source and the conditional CODEX_MCP_PRICING env var behavior. The read-only nature is reasonably implied by 'roll up ... from the local metrics log.' It could explicitly state side-effect-free behavior or missing-file handling, but the disclosure is solid.
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 tight sentences: the first front-loads the action, resource, and source path; the second specifies the exact env var JSON shape. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, data source, and optional cost-estimation setup, and the schema already documents all filters. Since there is no output schema, slightly more return-shape detail would improve completeness, but the mentioned 'token/duration/failure counts' and 'estCostUsd' provide a reasonable picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters and their filter meanings. The description adds no per-parameter detail beyond the schema, though it does provide useful context about the pricing environment variable affecting output.
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 names a specific verb and resource: 'Roll up token/duration/failure counts' from the local metrics log, with an exact file path. This clearly differentiates codex_metrics from the execution/session sibling tools by framing it as an aggregation/reporting tool.
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 says what the tool does but gives no guidance on when to use it instead of siblings like codex_sessions or codex_health. No exclusions, alternative conditions, or use-case context is provided, so the agent must infer when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It usefully discloses that deep mode runs one bounded, read-only Codex exec probe, which communicates safety and limits. It also explains why deep mode matters by mentioning quota/model outage detection, though it does not detail potential latency, failure semantics, or network dependencies beyond the output schema.
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 focused sentences with no filler. The main output is stated first, and the optional deep behavior is clearly introduced second. Every phrase earns its place, including 'bounded' and 'read-only,' which carry important safety information.
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?
The tool is simple: one optional boolean parameter, an output schema, and no nested structures. The description fully covers its purpose, the deep-mode extension, and the rationale for using it. Nothing needed for selecting or invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining why deep=true is useful—detecting quota/model outages that login status cannot see—rather than just restating the parameter's mechanics. This helps an agent decide whether to set deep=true.
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?
Description clearly states the tool reports installed Codex CLI version and login status, and optionally runs a health probe. This is a specific verb-resource pairing that makes the core purpose obvious, though it does not explicitly differentiate itself from sibling tools like codex_metrics or codex_sessions.
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 main purpose is clear: use this when you need CLI version, login status, or health-related outage detection. The deep=true behavior is explicitly tied to detecting quota/model outages that login status cannot see, providing a clear reason to enable it, but no direct comparisons or exclusions against sibling tools are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the transparency burden and does add meaningful context: the review runs in a read-only sandbox, modifies no files, and produces severity-ordered findings. It does not disclose execution duration, auto-resume behavior, or the writeNotes side effect; the 'no files modified' claim is also slightly broad given that writeNotes can persist a file.
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 sentences carry the full message efficiently, with the purpose front-loaded, the safety property in a parenthetical, and the output format plus follow-up hook stated at the end. There is no filler or repetition of schema details.
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 rich input schema and presence of an output schema mean the description does not need to restate parameter details or return structure. It provides the essential selection context and follow-up path, though explicitly naming execution-style alternatives such as codex_execute would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters are already described in the input schema, including nested fields, defaults, and constraints, so the schema coverage is 100%. The description adds no additional input-parameter meaning beyond referring to the returned sessionId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: 'review the uncommitted changes in a workspace.' It further distinguishes the tool from execution-style siblings by noting the read-only sandbox and that no files are modified, and it connects to codex_continue via the returned sessionId.
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 gives a clear trigger for when to use the tool: when uncommitted workspace changes should be reviewed by Codex. It also implies a follow-up workflow through codex_continue, but it does not explicitly mention alternatives or when-not conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses per-cwd locking, the need for distinct cwds, bounded parallelism, and ordered result entries. It does not detail failure behavior or auth requirements, but the core behavioral traits are well covered beyond what the schema shows.
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?
Three sentences with no filler. The opening sentence states the core operation and scope, the second adds the critical locking constraint, and the third clarifies the return shape. Every sentence earns its place.
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?
For a moderately complex batched tool, the description is complete: it explains parallelism, the workspace requirement, the uniqueness constraint, and the result ordering. The parameter schema covers the remaining details like defaults, limits, and timeouts, and an output schema exists, so return structure does not need to be restated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents tasks, failFast, and maxConcurrency. The description adds meaningful semantic context beyond the schema: distinct cwds are required because each task holds its own per-cwd lock, results are returned in input order, and parallelism is bounded. This helps an agent choose and fill parameters correctly.
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 fans out N tasks across N cwds in parallel, which is specific and distinct from the sibling tools that focus on single sessions or execution. It also names the resource (Codex tasks across workspaces) and includes the unique per-cwd lock requirement, so an agent can distinguish it from codex_execute or codex_sessions.
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 gives clear context for when to use this tool: multiple tasks, multiple cwds, typically git worktrees, with a bounded concurrency limit. It also states a hard prerequisite (distinct cwds). However, it does not explicitly name alternatives or state when not to use the batch tool, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does well to clarify the tool's behavior: it is a read-only operation that returns session metadata. It specifies the return structure and sorting. It does not mention side effects or permissions, but for a list tool this is acceptable.
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 three concise sentences with no redundancy. It front-loads the key information ('Discover Codex sessions') and provides essential details efficiently.
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 no output schema, the description adequately covers all essential aspects: what the tool does, its parameters, return values, and relation to sibling tools (codex_continue). For a simple list tool with two parameters, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the cwd filter's purpose ('to find sessions from a specific workspace') and implicitly references the limit parameter via the schema. This additional context raises the score above baseline.
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 tool's purpose: listing prior Codex sessions. It specifies the storage location, return fields (sessionId, cwd, last activity), and ordering (newest first). It also distinguishes itself by mentioning the connection to codex_continue for resuming sessions.
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 explains when to use the tool (to discover sessions) and provides a contextual use case: filtering by cwd to find sessions from a specific workspace. It also hints at the alternative of using codex_continue with the sessionId. However, it does not explicitly contrast with other siblings like codex_health or codex_review, so it loses a point for completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

codex-mcp MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![codex-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/anhnguyen0905/codex-mcp/badges/card.svg)](https://glama.ai/mcp/servers/anhnguyen0905/codex-mcp)

Score Badge

Copy to your README.md:

[![codex-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/anhnguyen0905/codex-mcp/badges/score.svg)](https://glama.ai/mcp/servers/anhnguyen0905/codex-mcp)