Skip to main content
Glama
Sign In
codex-mcp-bridge

codex-mcp-bridge

by buidangminh23
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Send a prompt to a Codex thread

send_to_codex_thread
Destructive

Sends a prompt as a new user turn into an existing Codex thread and waits for the reply, so you can continue the same unfinished task with full history, cwd, and model.

Instructions

Send a prompt as a new user turn inside an existing Codex thread and wait for Codex to answer. Use only for the same unfinished task, including follow-up fixes, clarifications, or results; independent new work belongs in a new conversation when authorized. The thread keeps its full history, cwd and model. Use list_codex_threads first if you do not know the threadId. Desktop-owned tasks must use Desktop native delivery; an open task is a valid destination. A Desktop send prepares a durable deliveryId before dispatch. An ambiguous acknowledgement is marked unconfirmed, never accepted without evidence. If it times out, continue automatically with wait_codex_reply using that ID; never resend to obtain the answer. If legacy delivery reports an active writer, inspect codex_bridge_status and repair the native relay/configuration. Do not close the task, create a replacement, or ask the user to copy the message manually.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "threadId": "<threadId>",
      "prompt": "<prompt>"
    },
    "name": "send_to_codex_thread"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNoExpected destination directory; Desktop always checks the verified sender's project and cannot change the task's workspace
nameNoOptional title to show for this Codex session
modelNoOverride the model for this turn
effortNoOverride reasoning effort (default whatever ~/.codex/config.toml says)
promptYesThe message to send to Codex as a new user turn. The prompt for the recipient agent, with an explicit From Codex or From Claude header naming the actual author, all agent-authored text in English including the header purpose, and the sections Goal, Context, Task, Scope, Constraints, Done when, Reply format (omit any that do not apply); text the user supplied is sent verbatim
threadIdYesCodex thread id (UUID) - get it from list_codex_threads
openInAppNoExplicitly open the thread in Codex Desktop so a human can watch it live. Default is false unless CODEX_BRIDGE_OPEN_IN_APP=1; normal delivery does not navigate or focus a window.
timeoutSecNoHow long to observe the task (Desktop caps the entire call at 40s; the task continues and its threadId is returned)
releaseAfterTurnNoUnsubscribe this thread after a terminal turn; open Desktop only after its unload is confirmed

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.26.3
    • changedInput schema / properties / openInApp / description
      Previous value: -"Open the thread in Codex Desktop on Windows or macOS so a human can watch it live"New value: +"Explicitly open the thread in Codex Desktop so a human can watch it live. Default is false unless CODEX_BRIDGE_OPEN_IN_APP=1; normal delivery does not navigate or focus a window."
  2. Changed1 schema field changedv1.23.0
    • removedInput schema / additionalProperties
      Removed value: -false
  3. Changed1 schema field changedv1.22.2
    • changedInput schema / properties / prompt / description
      Previous value: -"The message to send to Codex as a new user turn. The prompt for the recipient agent, in English with the sections Goal, Context, Task, Scope, Constraints, Done when, Reply format (omit any that do not apply); text the user supplied is sent verbatim"New value: +"The message to send to Codex as a new user turn. The prompt for the recipient agent, with an explicit From Codex or From Claude header naming the actual author, all agent-authored text in English including the header purpose, and the sections Goal, Context, Task, Scope, Constraints, Done when, Reply format (omit any that do not apply); text the user supplied is sent verbatim"
  4. Changed1 schema field changedv1.19.3
    • changedInput schema / properties / cwd / description
      Previous value: -"Override the working directory for this turn"New value: +"Expected destination directory; Desktop always checks the verified sender's project and cannot change the task's workspace"
  5. Changed1 schema field changedv1.18.0
    • changedInput schema / properties / prompt / description
      Previous value: -"The message to send to Codex, exactly as a user would type it"New value: +"The message to send to Codex as a new user turn. The prompt for the recipient agent, in English with the sections Goal, Context, Task, Scope, Constraints, Done when, Reply format (omit any that do not apply); text the user supplied is sent verbatim"
  6. Changed1 schema field changed
    • changedInput schema / properties / timeoutSec / description
      Previous value: -"How long to wait for the turn to finish (default 240s)"New value: +"How long to observe the task (Desktop caps the entire call at 40s; the task continues and its threadId is returned)"
  7. Changed1 schema field changedv1.12.3
    • changedInput schema / properties / releaseAfterTurn / description
      Previous value: -"Stop the bridge app-server after a terminal turn so Codex Desktop owns the writer lock"New value: +"Unsubscribe this thread after a terminal turn; open Desktop only after its unload is confirmed"
  8. First observedv1.11.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructive=true, openWorld=true, idempotent=false, and the description adds real behavioral context beyond them: a durable deliveryId is prepared before dispatch, ambiguous acknowledgements are marked unconfirmed rather than accepted, and Desktop calls are capped at 40s while the task continues. The no-resend and no-manual-copy rules are exactly the failure-mode guidance an agent needs.

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?

Purpose and the core usage constraint are front-loaded in the first two sentences, and no sentence is filler. The trailing runbook of edge cases (unconfirmed acks, legacy writer, don't close the task) is dense and slightly sprawling, but each clause maps to a real failure mode rather than restating the schema.

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 9-parameter, non-idempotent, destructive, long-running call with no output schema, the description covers the risky parts: sync vs. async behavior, the 40s Desktop cap, return of a threadId, and what to do on timeout or ambiguity. Nothing an agent must know to invoke it safely is missing.

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 each parameter carries a detailed description, so the schema does the heavy lifting and baseline 3 applies. The description only marginally supplements it, notably that the thread retains cwd and model, which hints that model/cwd are per-turn overrides rather than durable state changes.

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?

States a specific verb and resource (send a prompt as a new user turn inside an existing Codex thread) plus the blocking behavior (wait for the answer). It also draws the line against the obvious sibling by saying independent new work belongs in a new conversation, which separates it from start_codex_thread and delegate_to_codex.

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

Usage Guidelines5/5

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

Explicit when-to-use (same unfinished task, follow-up fixes, clarifications, results) and when-not (independent new work in a new conversation). It also routes to concrete siblings for the prerequisite and recovery paths: list_codex_threads when the threadId is unknown, wait_codex_reply on timeout, codex_bridge_status when a legacy writer blocks delivery.

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

Deploy Server

Other Tools