Claude MCP for Codex

A small, open-source MCP server that lets Codex ask Claude Code for a second opinion using your existing Claude Code login.

Codex -> stdio MCP -> Claude Code CLI -> Claude
      <- answer    <- JSON stream   <-

The server exposes one tool, ask_claude. Each call starts a fresh, text-only conversation. Supply the question and any sanitized code or context in the prompt. The initial version supports consultation; Claude's tools are disabled.

For code reviews, Claude returns findings and recommendations without editing files or running commands. Codex evaluates those findings and handles separately authorized code changes and validation. Claude receives only the supplied text; Codex must include the sanitized code or diff to be reviewed.

Requirements

• Node.js 22 or newer.

• macOS or Linux; Windows users can run the server and Claude Code inside WSL.

• A separately installed, authenticated Claude Code CLI supporting the flags listed below, including --safe-mode.

• Native stream-json initialization support; CLI-applied verification also needs the get_settings control response with applied model and effort.

• Codex or another MCP client with stdio support.

Claude Code owns authentication. This project does not implement an API backend, request an API key, install Claude Code, or open a login flow. Run Claude Code yourself to finish its setup before connecting this server. Calls consume usage under your Claude account's applicable limits.

Related MCP server: claude-consult-mcp

Build from source

Clone the public repository and enter its directory:

git clone https://github.com/daron4ever/claude-mcp-for-codex.git
cd claude-mcp-for-codex

Run these commands from the cloned repository. OSV Scanner 2.x is needed for the dependency precheck; it is not a runtime dependency. Stop if a scan reports vulnerabilities and assess them before installing.

npm install --package-lock-only --ignore-scripts
node scripts/check-lockfile.mjs
npm audit
osv-scanner scan source .

After the prechecks pass:

npm ci --ignore-scripts
npm run check

npm run check typechecks, builds, and runs synthetic tests without invoking the real Claude CLI. The executable is dist/index.js. This package has not been published to npm; use the local build for now.

Connect to Codex

Choose user scope (~/.codex/config.toml) for all your projects, or project scope (<project>/.codex/config.toml) for one trusted project. Project configuration takes precedence over user defaults. See official OpenAI configuration documentation.

Add the following table to your chosen Codex configuration, replacing the absolute path with your built checkout. This is a configuration example; the server does not modify Codex configuration itself.

[mcp_servers.claude]
command = "node"
args = ["/absolute/path/to/claude-mcp-for-codex/dist/index.js"]
tool_timeout_sec = 130

# Optional defaults; remove these two variables to use Claude runtime defaults.
[mcp_servers.claude.env]
CLAUDE_DEFAULT_MODEL = "claude-opus-5-5"
CLAUDE_DEFAULT_EFFORT = "medium"

Codex supports stdio commands, argument lists, forwarded environment variables, and tool timeouts. See Codex MCP configuration.

If node or claude is not on Codex's PATH, use an absolute path for command, and merge CLAUDE_BIN into the existing MCP environment table:

[mcp_servers.claude.env]
CLAUDE_BIN = "/absolute/path/to/claude"

Restart the Codex session after changing configuration. Confirm Codex recognizes the entry:

codex mcp list

Listing the entry confirms configuration discovery; it does not verify Claude authentication or a successful consultation. In the Codex CLI, use /mcp to inspect server status, then ask:

Use ask_claude to explain the tradeoffs in this approach. Include only the sanitized example supplied here.

Or call the tool with:

{
  "prompt": "Explain the tradeoffs of an in-memory queue for a single-process worker."
}

Optional project-scoped consultation skill

This repository includes an instruction-only Codex skill at .agents/skills/claude-consult/SKILL.md. It packages context preparation, argument selection, complete result retention, bounded reads, settings checks and reconciliation around the existing MCP tool. It does not change the server or automatically call Claude.

Codex discovers project skills under .agents/skills from its working directory up to the Git repository root. Start Codex in this repository or a subfolder to use the bundled skill. A sibling repository needs its own project-scoped copy; placing a skill above separate Git roots should not be assumed sufficient. See official skill discovery documentation.

For another project, copy the skill into that project's repository root, after checking that the destination does not already exist. From this checkout:

target_project="/absolute/path/to/your/project"
mkdir -p "$target_project/.agents/skills"
if [ ! -e "$target_project/.agents/skills/claude-consult" ] && \
  [ ! -L "$target_project/.agents/skills/claude-consult" ]; then
  cp -R .agents/skills/claude-consult "$target_project/.agents/skills/"
else
  echo "Destination exists; inspect it before updating."
fi

These are optional manual installation commands; the server does not execute them. No user-scoped skill or configuration is installed. The skill is also included in package contents. No plugin registration or tool installation is performed. Keep the existing Claude MCP connection configured separately; skill scope and MCP configuration scope are independent.

Invoke it in Codex with an authorized consultation, for example:

$claude-consult Explain the tradeoffs in the approved task using opus/high.

It can also be selected automatically for matching requests; selection does not authorize a call. Verify that it appears in your client's skill selector. Current Codex detects skill updates automatically; if it does not appear, restart the client after protecting any session-only retained answers. Discovery is separate from successful MCP execution. Existing project policy still governs calls and formal reviews, including Codex-only review rules where applicable.

Keep consultation triggers, access/approval rules and required verification in AGENTS.md so they apply even when the skill is not loaded. The skill carries the detailed mechanics; adopting it does not automatically remove duplicated instructions or edit any project's AGENTS.md. Result retention uses available client/session facilities, not server-side storage, and cannot recover an earlier unretained response. This workflow is not an authentication or timeout fix.

Select context before consulting Claude

Use Codex's existing code-navigation tools to gather relevant context before calling ask_claude. This workflow uses the current prompt argument; the server does not search files, maintain an index, or automatically load these instructions. To adopt it, add the guidance below to your applicable AGENTS.md.

Include the current task's progress as well as relevant code. Each Claude call starts fresh: a task number or a file path alone does not supply earlier work. Codex prepares the task snapshot and includes it in the existing prompt; Claude does not read the task registry or remember previous calls automatically.

Before: Codex -> question + caller-assembled context -> Claude MCP

After:  current task record + authorized source
              -> Codex refreshes and sanitizes task snapshot + snippets
              -> bounded prompt -> fresh Claude MCP call -> assessment
              -> Codex checks evidence and handles approved changes

## Context for Claude consultations
- Apply this workflow only when a Claude consultation is already authorized.
  Preserve the project's consultation and formal-review rules.
- State the decision, expected behavior and relevant constraints. Independently
  analyze the evidence before reading Claude's response.
- Before each authorized call, refresh the relevant task state from its current
  task record and authorized source. If there is no task record, use confirmed
  conversation facts and label unknowns; do not invent progress or decisions.
- Include the task identity, goal, approved scope, current step, completed work,
  remaining work and the specific question Claude should assess. Distinguish
  executed validation and its results from planned or unverified checks.
- Include settled requirements, approved decisions and their reasons. Label
  earlier Claude recommendations as advisory and state whether they were adopted,
  rejected or remain unresolved. Do not send raw conversation transcripts or
  Codex's tentative conclusions and preferred answer.
- Identify the source revision or working-tree state and changes since the last
  consultation. Supply the complete relevant current snapshot on every call;
  a task ID, previous-call reference or change-only update is insufficient.
- Use existing code-navigation tools within approved access. Read the named
  function and relevant callers, state owners or tests; do not send whole files
  when selected excerpts provide enough context.
- Send only minimized, sanitized source excerpts. Never include credentials,
  .env contents, customer data, production exports or raw production logs.
  Automated filtering alone does not establish that context is safe to share.
- Label excerpts with project-relative paths and original line numbers. State
  which revision or working-tree state they describe. Label redactions and gaps;
  snippets must not imply that omitted code was inspected or is absent.
- Keep the complete prompt within 200000 UTF-8 bytes, including the question,
  labels and constraints. Reduce irrelevant context explicitly; never silently
  truncate. If necessary evidence cannot fit or cannot safely be shared, report
  the limitation and request a narrower decision or additional authorization.
- Supply the applicable model and effort choices as tool arguments. Treat
  requested settings, CLI-reported models and verified settings separately;
  honor any rule requiring verified effective settings before relying on Claude.
- Ask Claude for findings, tradeoffs and uncertainty using only supplied context.
  Codex checks the claims against source and handles separately approved edits.
  Missing context requires further evidence, not automatic retries or acceptance.
- When the answer arrives, check it against the latest task and source state.
  Reconcile stale assumptions before using the advice; do not automatically
  repeat the call. Record concise adopted recommendations and reconciliation
  reasons in the existing task record, without copying the transcript.

For example, this valid tool request supplies a synthetic task snapshot and code excerpt. The task, progress and decisions below are illustrative, not results from this repository. Use the model and effort required by your own instructions.

{
  "prompt": "Task snapshot: synthetic example, task #3.\nGoal: cancellation stops this worker. Approved scope: cancellation behavior only; no unrelated changes.\nCurrent step: assess behavior when cancellation arrives during job execution.\nCompleted work: added the pre-start cancellation check shown below. Validation: no checks have been executed in this example.\nRemaining work: establish the job's cancellation contract, implement any approved correction, and validate the affected flow.\nSettled decision: Codex owns edits; Claude provides advice only. Prior Claude advice: none.\nChanges since the previous consultation: first consultation. Source state: synthetic excerpt, no repository revision.\nEvidence: worker.js lines 1-4:\n1 export async function run(job, signal) {\n2   if (signal.aborted) throw new Error('cancelled');\n3   return await job();\n4 }\nCoverage: job implementation and callers are not supplied; do not assume their behavior.\nQuestion: what evidence is needed to assess cancellation during job execution? Return findings, options and uncertainty using only supplied context. Do not edit files or run tools.",
  "model": "opus",
  "effort": "high"
}

The 200,000-byte input allowance covers the complete supplied prompt, including the question, labels and source excerpts. It is separate from the cumulative 1 MiB CLI stdout guard, response length and request deadline; bytes are not a model-context token guarantee. More input room does not establish complete source coverage or prevent timeouts. If necessary evidence still cannot fit, disclose the coverage gap and narrow the authorized question before calling rather than claiming omitted persistence, replay or other critical paths were assessed.

After an upgrade from the earlier 100,000-byte limit, rebuild this checkout and refresh the affected MCP connection when idle to load the new input schema. Update any separately installed skill and applicable project prompt-budget rule to match; a repository update alone does not update those copies. Do not interrupt active calls or discard session-retained answers merely to refresh the limit.

The wrapper validates the prompt's size and shape, but cannot establish that it is sanitized, sufficient, current or correctly attributed. Codex owns those checks. Adopting this guidance supplies task continuity through updated prompts; it adds no server-side memory, automatic file loading or session resumption. Smaller, relevant context may help large consultations; this workflow has not been shown to resolve intermittent timeouts and does not verify applied model or effort. A separate semantic index is optional infrastructure, not required for this flow.

Keep long Claude responses available

Codex can truncate oversized tool output before its model reads it. Increasing the tool-output budget gives headroom, but does not retain an omitted answer.

When your Codex client exposes Code Mode with store and load, use this caller workflow for an authorized consultation:

1. Discover and validate the live Claude tool definition. Send only approved, minimized, sanitized context and the applicable model/effort arguments.

2. Call Claude through Code Mode and store the complete returned result under a distinct key before printing anything. Print only that key, success/error status, answer size, and the execution metadata.

3. Load the retained result in later cells and print bounded answer sections. Account for UTF-8 size, JSON escaping and the active output budget; a fixed character count is not a guaranteed token bound. If a section is truncated, read a smaller section from the same retained result.

4. Track coverage and read all relevant sections before presenting Claude's conclusions. Label any incomplete assessment. Retrieving a section does not require another Claude call.

5. Keep requested settings, CLI-reported usage and effective-setting evidence separate. This workflow does not verify applied effort or waive your consultation, review or access requirements.

Before: Claude -> direct tool output -> client budget -> omitted sections

After:  Claude -> Code Mode store -> bounded reads -> Codex assessment

The retained result belongs to the current Code Mode session. Do not assume it survives a restart, compaction, or client recovery unless the client documents and verifies that behavior. This workflow does not retrospectively recover a previous direct call. Do not write responses to disk without approval.

If Code Mode, store or load is unavailable, request a concise assessment and use the documented tool-output budget when supported by your installed Codex version. Report incomplete output; do not silently repeat a paid consultation.

To adopt this workflow, copy the following guidance into your applicable AGENTS.md. The server does not automatically retain results or load it.

## Retain Claude consultation results
- For an authorized Claude consultation, when Code Mode store/load is available,
  retain the complete result under a distinct session key before printing it.
- Print bounded status/metadata, then load and read answer sections within the
  active output budget. Read all relevant sections before assessing findings.
- Retrieve missing sections from the retained result rather than calling Claude
  again. If retention or output coverage is unavailable, disclose the limitation.
- Preserve existing access, sanitation, model/effort verification, consultation,
  formal-review and implementation-approval requirements. Do not persist answers
  to files without approval.

Execution metadata and failures

Successful calls keep Claude's answer unchanged in the first MCP text block. A second text block names the CLI-applied evidence status and includes execution metadata. structuredContent contains the same answer and metadata under the advertised output schema. An illustrative opus/high call with complete evidence returns:

{
  "answer": "Claude's answer...",
  "metadata": {
    "requestedModel": "opus",
    "requestedEffort": "high",
    "cliReportedModelIds": ["claude-haiku-4-5-20251001", "claude-opus-5-5"],
    "modelUsageStatus": "reported",
    "effectiveModelVerified": true,
    "effectiveEffortVerified": true,
    "settingsEvidence": {
      "scope": "cli_applied_session",
      "status": "verified",
      "before": { "model": "claude-opus-5-5", "effort": "high" },
      "after": { "model": "claude-opus-5-5", "effort": "high" },
      "answerModelIds": ["claude-opus-5-5"],
      "sessionCorrelated": true,
      "requestedModelMatch": "alias_unchecked",
      "requestedEffortMatched": true,
      "providerAttested": false,
      "reasoningAllocationVerified": false
    }
  }
}

The effective*Verified flags now mean answer-correlated CLI-applied session settings, within settingsEvidence.scope. They require successful native initialization, matched before/after get_settings responses, valid stable applied model and effort, matching main-assistant model(s), and consistent internal init, main-assistant and result session IDs. Main-answer evidence requires explicit root attribution (parent_tool_use_id: null), an assistant role, supported content blocks and a nonblank text block. Valid thinking blocks may precede the text answer; thinking alone does not establish answer evidence. Missing or malformed envelopes leave verification false. Flags are computed by the wrapper; values supplied in an answer, result metadata or aggregate usage cannot establish them. The wrapper returns only after normal process exit, close and group cleanup.

initialize -> settings before -> one prompt -> main answer/result
           -> settings after -> correlate -> EOF/exit/cleanup -> MCP response

This is independent of the model's textual claims, but not provider-side per-request attestation. It does not establish internal reasoning allocation or that a silent inference-stage effort cap is reflected in the readback. Both providerAttested and reasoningAllocationVerified remain false. A policy that requires provider-effective settings beyond CLI-applied evidence remains unsatisfied; callers must apply their own verification policy before relying on an assessment.

requestedModel and requestedEffort are passed values after argument/default precedence; null delegates to Claude defaults. The CLI owns alias resolution: alias_unchecked reports that an alias was supplied without claiming the wrapper independently knows its latest version or mapping. cli_default means the model flag was omitted. A supplied full claude-... ID is compared literally (exact or different); unavailable readback yields unavailable. Supplied effort is compared with the before-readback, or null when not supplied/unavailable. A full ID or effort mismatch prevents verification. The example is not a guarantee of what opus resolves to for every account or CLI version.

settingsEvidence.status is verified, unavailable for missing fields or unsupported readback, invalid for malformed evidence, or mismatch for contradictory settings, sessions, answer models or explicit selections. Only allowlisted model/effort pairs are returned in before/after; unavailable or invalid snapshots are null. Main-answer IDs are distinct from aggregate usage. A structurally valid answer is preserved on evidence-only failure with both flags false; this does not authorize strict callers to rely on it. Broken control ordering, unsuccessful results, transport failures or cleanup failures return errors without an answer. Unsupported readback never triggers a retry or a second inference request.

modelUsageStatus separately describes aggregate usage: reported for valid nonempty IDs, unavailable for absent/empty usage, and invalid for unsupported shape or IDs. Malformed usage does not invalidate otherwise valid settings evidence or answer text. Extraction accepts at most 16 claude-... IDs of up to 128 characters; auxiliary models may appear here. Usage values, raw session IDs, full settings, error payloads and unrelated CLI fields are never returned.

Failures set isError: true. The first text block starts with the short error message, followed after CLI launch by a compact summary of phase, elapsed time, observed response/retry events and exit/close/cleanup state. This keeps activity information near the beginning when a client collapses or truncates output. A second text block remains labeled Claude failure diagnostics (initial state before cleanup):, followed by JSON such as:

{
  "failureCategory": "timeout",
  "failureReason": null,
  "cliResultSubtype": null,
  "cliApiErrorStatus": null,
  "cliApiErrorStatusState": "not_applicable",
  "cliPrecedingAssistantError": null,
  "cliPrecedingAssistantErrorState": "not_applicable",
  "phase": "initialize",
  "elapsedMs": 300004,
  "responseEventCount": 0,
  "lastResponseEventAgeMs": null,
  "retryEventCount": 0,
  "timeoutMs": 300000,
  "firstStdoutMs": null,
  "stdoutBytes": 0,
  "stderrBytes": 0,
  "exitObserved": false,
  "exitCode": null,
  "exitSignal": null,
  "closeObserved": false,
  "cleanupStatus": "close_observed"
}

This is an illustrative timeout, not a runtime measurement. elapsedMs uses a monotonic clock from launch to the initial failure, excluding cleanup; timeoutMs is the configured deadline in that running server. firstStdoutMs is the first received stdout time from launch, or null when none arrived. Byte counts describe output received before failure, not its content or validity. exitObserved, exitCode, exitSignal and closeObserved describe the initial failure boundary before wrapper termination; null exit fields alone do not establish that the CLI was still running. An observed exit with no close can indicate still-open stdio pipes. Output bytes do not establish a completed assessment or identify a network/model issue.

phase records the native lifecycle boundary: initialize, settings_before, inference, settings_after, or closing. It locates the wait; it does not establish why the call did not complete.

responseEventCount counts structurally valid main assistant and successful result frames observed by the wrapper. Control messages, initialization, auxiliary messages and malformed response evidence do not count. lastResponseEventAgeMs is the monotonic time since the latest such frame at the initial failure, or null if none was observed. retryEventCount counts well-formed system/api_retry events received during inference, not total API attempts. Some retries are silent, and the CLI can buffer output. These fields describe local observations; silence never proves Claude or the provider stalled.

failureCategory records the first wrapper boundary: timeout, cancelled, spawn, stdin, stdout, stderr, stdout_limit, stderr_limit, cli_exit, invalid_result, protocol or cleanup. protocol covers broken control/event sequencing, premature close and unsupported operation requests. cleanupStatus separately describes the final cleanup observation: close_observed means the immediate child closed and no process-group signaling failure was observed; unconfirmed means cleanup could not be confirmed. It does not attest to descendants outside the process group. A cleanup failure can replace the first error message while retaining the original category and snapshot.

For invalid_result, failureReason distinguishes the rejecting check:

cliResultSubtype is populated only for cli_error_result: success, error_during_execution, error_max_turns, error_max_budget_usd, or error_max_structured_output_retries. It identifies the CLI's declaration, not a verified provider cause or validation of every error-envelope field. Unknown strings and raw errors bodies are never echoed. Both new fields are null for other failure categories. The broad invalid_result category remains unchanged; existing saved generic failures cannot be retrospectively classified from byte counts alone. Human-readable error messages also distinguish decoding/parsing, invalid envelopes and recognized unsuccessful results.

The CLI can return subtype: "success" with is_error: true when a turn ends in an API error, as documented in the published SDK contract. Here success is the envelope subtype, not a successful assessment. The bridge reports cli_error_result, discards the error text and returns no assessment. It does not infer authentication, billing, model availability or another provider cause from the subtype alone. Valid assessments still require is_error: false and all existing success checks. Increasing the deadline cannot fix this early CLI-declared failure.

For cli_error_result, the bridge also projects structured CLI observations:

The category allowlist follows the published SDK contract: authentication_failed, oauth_org_not_allowed, account_on_hold, verification_required, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, unknown, max_output_tokens, and cloud_credential_error. A literal CLI category unknown is distinct from an unrecognized arbitrary string; arbitrary values are never echoed.

Reporting a category requires an explicit top-level assistant frame, an assistant role, and a session matching both initialization and the final failed result. Synthetic error frames do not need an ordinary answering-model ID. Explicit auxiliary frames are ignored. Missing or invalid attribution is uncorrelated; malformed category/envelope data is invalid. Different recognized categories in an unresolved segment are conflicting, with no selected category. A later valid, correlated ordinary response or retry supersedes earlier error evidence; a fresh error after that transition can establish a new candidate. Unrecognized or malformed relevant evidence cannot silently expose an older category.

For example, a synthetic failure could report cliApiErrorStatus: 429 and cliPrecedingAssistantError: "rate_limit", each with state reported. These are separate CLI-reported observations: no category is inferred from a status, and neither proves the provider/account root cause or credential validity. Retry-event status/category values are not used as terminal error evidence. If the CLI omits the information, the availability states explain that limitation; the bridge does not read private logs or make another Claude request to fill the gap. Existing saved failures cannot be enriched retrospectively.

For other failure reasons/categories these values are null with states not_applicable. They never appear in successful answer metadata. Available validated status/category values also appear in the short error message; raw result/error text, session/request IDs and account details remain private.

CLI error -> validated terminal status + correlated preceding category (or unavailable)
          -> frozen error diagnostics -> discard assessment -> bounded cleanup

These fields share the frozen initial-failure boundary. A later cleanup error does not replace them. Failed calls still return no assessment or successful settings-verification metadata, and the request deadline remains unchanged.

Failure diagnostics contain no prompts, paths, settings, raw CLI output, partial answers or model/effort verification claims. Error responses do not include successful execution metadata or structuredContent. Input validation and cancellation before launch can return only the short message. A client/transport timeout that prevents the server response from arriving cannot carry these diagnostics.

Live progress

Clients that supply an MCP progress token can receive content-free phase, elapsed time, response event count/age and observed retry count while a call runs. Notifications are limited to one per second and coalesced to the latest state, with a timing update every ten seconds during quiet periods. The increasing progress number is a notification sequence, not a completion percentage or evidence of provider activity. No token means no notifications. The token is echoed only in the required protocol field, never in the progress message.

Reporting stops when the request succeeds, fails, is cancelled or shuts down. Notification failures or backpressure do not delay the absolute deadline, answer or cleanup. No text/thinking deltas, raw errors, settings or session IDs are exposed, and partial-message streaming stays disabled to preserve the existing cumulative output budget.

Visible progress requires client support. The inspected upstream Codex handler logs progress without forwarding it to the visible UI; installed Codex behavior may differ and is unverified. The compact final failure summary remains useful when live notifications are not displayed. No stall detector or automatic retry is introduced. The twenty-minute deadline is unchanged.

Accepted Claude frames -> per-call timing/counts -> supporting MCP client
Failure                -> frozen snapshot -> summary + diagnostics
Terminal state         -> stop reporting -> existing cleanup

Codex can follow a review policy in your project AGENTS.md or user ~/.codex/AGENTS.md. For example:

## Code reviews
- When a review is requested, call the Claude MCP tool `ask_claude`.
- Use model `best` with effort `high` for reviews only.
- Supply only sanitized code and context. Ask for findings and recommendations only.
- Codex evaluates the findings and handles fixes under the project's approval rules.

This instruction directs Codex to pass the model and effort as tool arguments. The server does not read AGENTS.md itself. Claude Code's best alias selects the model that fable resolves to when Fable is available to your account, otherwise the same model as opus. Alias versions depend on the CLI/provider; use claude-fable-5-1 when you need that exact version rather than an evolving alias. See Claude model configuration and official OpenAI AGENTS.md documentation.

Resolve each field independently in this order:

1. Codex passes the applicable AGENTS.md choice as a tool argument.

2. For an omitted argument, the server uses its configured default from config.toml.

3. If both sources omit the field, the server leaves its CLI flag out and Claude Code selects its runtime default under the restricted launch described below.

For example, add these optional defaults to your chosen Codex configuration. Merge them into an existing [mcp_servers.claude.env] table if you already have one:

[mcp_servers.claude.env]
CLAUDE_DEFAULT_MODEL = "claude-opus-5-5"
CLAUDE_DEFAULT_EFFORT = "medium"

Normal consultation calls with no model/effort arguments use Opus 5.5 and medium effort. The review policy above makes Codex pass best and high, overriding both configured defaults. Supplying only one argument overrides only that field. Directly supplied tool arguments also override the server defaults; the wrapper cannot distinguish arguments chosen from instructions from manually supplied arguments. Invalid supplied arguments fail validation, and invalid configured defaults prevent startup rather than silently falling back.

Configuration

Set Codex's tool_timeout_sec longer than this timeout plus the two-second cleanup allowance. No .env file is loaded. For an existing login stored in a nonstandard Claude configuration directory, forward your existing CLAUDE_CONFIG_DIR through Codex's env_vars; the wrapper does not inspect that directory.

For a twenty-minute deadline, merge these values into your existing Claude MCP tables in the chosen user or project configuration; preserve the command, arguments and other environment entries:

[mcp_servers.claude]
tool_timeout_sec = 1210

[mcp_servers.claude.env]
CLAUDE_TIMEOUT_MS = "1200000"

Restart the MCP connection after changing the configuration. The deadline covers CLI startup, settings readbacks, inference and process completion. Increasing it allows slower calls more time; it does not establish why an earlier call timed out.

Process and data boundaries

The wrapper spawns the executable directly with shell: false and passes the prompt through stdin. Prompts are absent from the command-line arguments. It invokes Claude Code with:

--print --input-format stream-json --output-format stream-json --verbose
--safe-mode
--tools "" --disallowedTools "*"
--strict-mcp-config --mcp-config '{"mcpServers":{}}'
--disable-slash-commands --no-session-persistence
--permission-mode default --setting-sources ""
--settings '{"disableAllHooks":true}'

The wrapper adds --model <model> and --effort <effort> only when their fields are supplied by tool arguments or configured defaults. It does not enforce a built-in model or effort fallback. Regular Claude user/project/local settings are disabled by the restricted launch; delegating to Claude defaults does not re-enable those settings. Invalid tool argument values are rejected before launch. Claude Code determines the effective model and effort, and may lower effort to a level supported by the model or allowed by organization policy; the wrapper checks CLI-applied answering-session settings as described above, without attesting to provider-side execution or reasoning allocation. See Claude effort levels. CLI failures are returned without an automatic retry or fallback by this wrapper.

--safe-mode skips regular customizations while preserving authentication. --bare is intentionally not used: it skips subscription credentials. Built-in and MCP tools are denied. See the CLI reference and programmatic use.

Only a fixed set of environment variables for executable discovery, local authentication location, locale, proxies, and CA certificates is forwarded. API keys, provider selectors, injected Node options, and unrelated environment secrets are omitted. CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 is set. The wrapper stores no prompts or answers and never logs raw stderr or unsuccessful stdout.

Claude Code remains responsible for its own authentication, network traffic, and local operational state. These flags are not an OS sandbox. Managed organization policy still applies, and managed hooks cannot be disabled by these user-level flags. See Claude Code hooks. Account administrators remain responsible for managed policy. Only explicitly supplied, sanitized text should be sent: never .env contents, secrets, credentials, production exports, or customer data.

Each request has independent state. Cancellation, timeout, and shutdown send SIGTERM to its POSIX process group, then SIGKILL after 500 ms. Cleanup waits at most two seconds and reports failure if the immediate child's close cannot be confirmed. Descendants that deliberately escape the process group are outside this cleanup boundary. The single request deadline covers initialization, both readbacks, inference and process close. Stdout is limited to 1 MiB cumulatively across all control and answer frames, and stderr to 64 KiB. Verbose frames repeat answer content, so the largest answer that fits can be smaller than with final JSON output. No automatic retries or session resumption occur.

Troubleshooting

• Could not start Claude Code: install the CLI separately or set CLAUDE_BIN to its executable. Shell aliases and .cmd wrappers are not supported.

• Claude Code failed: check installation, authentication, model availability, and flag support directly in your terminal. Unsupported flags fail the call; the server never retries with weaker restrictions.

• Invalid or unsuccessful result: inspect failureReason and cliResultSubtype. A valid JSON error declaration is distinct from malformed JSON or an invalid success envelope; raw error text stays private. Increasing the timeout does not address an early parse/result rejection. The CLI version and underlying cause still require separate evidence.

• Timed out: inspect the compact activity summary and diagnostics' phase, actual timeoutMs, elapsed time, observed response/retry events and initial exit/close observations. These identify the wrapper boundary, not its root cause; no observed event does not prove a stall. If changing CLAUDE_TIMEOUT_MS, also leave the MCP client's timeout longer than the deadline plus cleanup, then restart the MCP connection to load the change. A client timeout or stale running server requires separate evidence.

• Unverified CLI-applied settings: inspect settingsEvidence.status and the sanitized snapshots; update Claude Code if native readback is unsupported. Follow your verification policy instead of assuming requested settings applied.

• Native protocol failure: use a compatible Claude Code CLI. Unexpected control requests and broken sequencing fail without approving tools or retrying.

• Invalid or unsuccessful JSON result: update to a compatible Claude Code CLI and check its behavior locally. Raw error payloads are deliberately not relayed.

Local synthetic tests establish the wrapper's protocol and process behavior. They do not establish login health, model availability, or compatibility with a particular installed Claude Code version. Validate those separately before relying on the integration.

Development and release

The runtime uses the official MCP TypeScript SDK and Zod. Tests use Node's built-in test runner and an executable fixture created under the ignored .cache/ directory. CI repeats the checks on macOS and Linux with Node.js 22 and 24.

For dependency changes, resolve the lockfile with scripts disabled, run npm audit and OSV Scanner, inspect changed package sources and install-script metadata, then install only after the checks pass. Keep changes focused and use synthetic test data.

Build and inspect the release package locally:

npm run build
npm pack --ignore-scripts

The GitHub repository is maintained under daron4ever/claude-mcp-for-codex. npm publication is a separate maintainer action; this package has not been published to npm. This is an independent community project, not an official Anthropic or OpenAI product. It is licensed under MIT; Claude Code remains separately distributed by Anthropic.