71 Commits

• chore: move mcp-server/src/wire_format.rs to protocol/src/mcp_protocol.rs (#2423)

  The existing `wire_format.rs` should share more types with the
  `codex-protocol` crate (like `AskForApproval` instead of maintaining a
  parallel `CodexToolCallApprovalPolicy` enum), so this PR moves
  `wire_format.rs` into `codex-protocol`, renaming it as
  `mcp-protocol.rs`. We also de-dupe types, where appropriate.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/2423).
  * #2424
  * __->__ #2423

  Michael Bolin · 2025-08-18 09:36:57 -07:00
  712bfa04ac
• remove mcp-server/src/mcp_protocol.rs and the code that depends on it (#2360)
  Michael Bolin · 2025-08-18 00:29:18 -07:00
  a269754668
• fix: add support for exec and apply_patch approvals in the new wire format (#2286)

  Now when `CodexMessageProcessor` receives either a
  `EventMsg::ApplyPatchApprovalRequest` or a
  `EventMsg::ExecApprovalRequest`, it sends the appropriate request from
  the server to the client. When it gets a response, it forwards it on to
  the `CodexConversation`.
  
  Note this takes a lot of code from:
  
  
  https://github.com/openai/codex/blob/main/codex-rs/mcp-server/src/conversation_loop.rs
  
  https://github.com/openai/codex/blob/main/codex-rs/mcp-server/src/exec_approval.rs
  
  https://github.com/openai/codex/blob/main/codex-rs/mcp-server/src/patch_approval.rs
  
  I am copy/pasting for now because I am trying to consolidate around the
  new `wire_format.rs`, so I plan to delete these other files soon.
  
  Now that we have requests going both from client-to-server and
  server-to-client, I renamed `CodexRequest` to `ClientRequest`.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/2286).
  * #2287
  * __->__ #2286
  * #2285

  Michael Bolin · 2025-08-13 23:00:50 -07:00
  539f4b290e
• feat: support traditional JSON-RPC request/response in MCP server (#2264)

  This introduces a new set of request types that our `codex mcp`
  supports. Note that these do not conform to MCP tool calls so that
  instead of having to send something like this:
  
  ```json
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 42,
    "params": {
      "name": "newConversation",
      "arguments": {
        "model": "gpt-5",
        "approvalPolicy": "on-request"
      }
    }
  }
  ```
  
  we can send something like this:
  
  
  ```json
  {
    "jsonrpc": "2.0",
    "method": "newConversation",
    "id": 42,
    "params": {
      "model": "gpt-5",
      "approvalPolicy": "on-request"
    }
  }
  ```
  
  Admittedly, this new format is not a valid MCP tool call, but we are OK
  with that right now. (That is, not everything we might want to request
  of `codex mcp` is something that is appropriate for an autonomous agent
  to do.)
  
  To start, this introduces four request types:
  
  - `newConversation`
  - `sendUserMessage`
  - `addConversationListener`
  - `removeConversationListener`
  
  The new `mcp-server/tests/codex_message_processor_flow.rs` shows how
  these can be used.
  
  The types are defined on the `CodexRequest` enum, so we introduce a new
  `CodexMessageProcessor` that is responsible for dealing with requests
  from this enum. The top-level `MessageProcessor` has been updated so
  that when `process_request()` is called, it first checks whether the
  request conforms to `CodexRequest` and dispatches it to
  `CodexMessageProcessor` if so.
  
  Note that I also decided to use `camelCase` for the on-the-wire format,
  as that seems to be the convention for MCP.
  
  For the moment, the new protocol is defined in `wire_format.rs` within
  the `mcp-server` crate, but in a subsequent PR, I will probably move it
  to its own crate to ensure the protocol has minimal dependencies and
  that we can codegen a schema from it.
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/2264).
  * #2278
  * __->__ #2264

  Michael Bolin · 2025-08-13 17:36:29 -07:00
  e7bad650ff
• fix: update OutgoingMessageSender::send_response() to take Serialize (#2263)

  This makes `send_response()` easier to work with.

  Michael Bolin · 2025-08-13 14:29:13 -07:00
  37fc4185ef
• chore: introduce ConversationManager as a clearinghouse for all conversations (#2240)

  This PR does two things because after I got deep into the first one I
  started pulling on the thread to the second:
  
  - Makes `ConversationManager` the place where all in-memory
  conversations are created and stored. Previously, `MessageProcessor` in
  the `codex-mcp-server` crate was doing this via its `session_map`, but
  this is something that should be done in `codex-core`.
  - It unwinds the `ctrl_c: tokio::sync::Notify` that was threaded
  throughout our code. I think this made sense at one time, but now that
  we handle Ctrl-C within the TUI and have a proper `Op::Interrupt` event,
  I don't think this was quite right, so I removed it. For `codex exec`
  and `codex proto`, we now use `tokio::signal::ctrl_c()` directly, but we
  no longer make `Notify` a field of `Codex` or `CodexConversation`.
  
  Changes of note:
  
  - Adds the files `conversation_manager.rs` and `codex_conversation.rs`
  to `codex-core`.
  - `Codex` and `CodexSpawnOk` are no longer exported from `codex-core`:
  other crates must use `CodexConversation` instead (which is created via
  `ConversationManager`).
  - `core/src/codex_wrapper.rs` has been deleted in favor of
  `ConversationManager`.
  - `ConversationManager::new_conversation()` returns `NewConversation`,
  which is in line with the `new_conversation` tool we want to add to the
  MCP server. Note `NewConversation` includes `SessionConfiguredEvent`, so
  we eliminate checks in cases like `codex-rs/core/tests/client.rs` to
  verify `SessionConfiguredEvent` is the first event because that is now
  internal to `ConversationManager`.
  - Quite a bit of code was deleted from
  `codex-rs/mcp-server/src/message_processor.rs` since it no longer has to
  manage multiple conversations itself: it goes through
  `ConversationManager` instead.
  - `core/tests/live_agent.rs` has been deleted because I had to update a
  bunch of tests and all the tests in here were ignored, and I don't think
  anyone ever ran them, so this was just technical debt, at this point.
  - Removed `notify_on_sigint()` from `util.rs` (and in a follow-up, I
  hope to refactor the blandly-named `util.rs` into more descriptive
  files).
  - In general, I started replacing local variables named `codex` as
  `conversation`, where appropriate, though admittedly I didn't do it
  through all the integration tests because that would have added a lot of
  noise to this PR.
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/2240).
  * #2264
  * #2263
  * __->__ #2240

  Michael Bolin · 2025-08-13 13:38:18 -07:00
  08ed618f72
• MCP: add conversation.create tool [Stack 2/2] (#1783)

  Introduce conversation.create handler (handle_create_conversation) and
  wire it in MessageProcessor.
  
  Stack:
  Top: #1783 
  Bottom: #1784
  
  ---------
  
  Co-authored-by: Gabriel Peal <gpeal@users.noreply.github.com>

  aibrahim-oai · 2025-08-01 22:18:36 +00:00
  97ab8fb610
• Introduce a new function to just send user message [Stack 3/3] (#1686)

  - MCP server: add send-user-message tool to send user input to a running
  Codex session
  - Added an integration tests for the happy and sad paths
  
  Changes:
  •	Add tool definition and schema.
  •	Expose tool in capabilities.
  •	Route and handle tool requests with validation.
  •	Tests for success, bad UUID, and missing session.
  
  
  follow‑ups
  • Listen path not implemented yet; the tool is present but marked “don’t
  use yet” in code comments.
  • Session run flag reset: clear running_session_id_set appropriately
  after turn completion/errors.
  
  This is the third PR in a stack.
  Stack:
  Final: #1686
  Intermediate: #1751
  First: #1750

  aibrahim-oai · 2025-08-01 17:04:12 +00:00
  f918198bbb
• MCP server: route structured tool-call requests and expose mcp_protocol [Stack 2/3] (#1751)

  - Expose mcp_protocol from mcp-server for reuse in tests and callers.
  - In MessageProcessor, detect structured ToolCallRequestParams in
  tools/call and forward to a new handler.
  - Add handle_new_tool_calls scaffold (returns error for now).
  - Test helper: add send_send_user_message_tool_call to McpProcess to
  send ConversationSendMessage requests;
  
  This is the second PR in a stack.
  Stack:
  Final: #1686
  Intermediate: #1751
  First: #1750

  aibrahim-oai · 2025-08-01 02:46:04 +00:00
  ad0295b893
• Adding interrupt Support to MCP (#1646)
  aibrahim-oai · 2025-07-22 20:33:49 +00:00
  01c0896f0f
• [mcp-server] Add reply tool call (#1643)

  ## Summary
  Adds a new mcp tool call, `codex-reply`, so we can continue existing
  sessions. This is a first draft and does not yet support sessions from
  previous processes.
  
  ## Testing
  - [x] tested with mcp client

  Dylan · 2025-07-21 21:01:56 -07:00
  18b2b30841
• test: add integration test for MCP server (#1633)

  This PR introduces a single integration test for `cargo mcp`, though it
  also introduces a number of reusable components so that it should be
  easier to introduce more integration tests going forward.
  
  The new test is introduced in `codex-rs/mcp-server/tests/elicitation.rs`
  and the reusable pieces are in `codex-rs/mcp-server/tests/common`.
  
  The test itself verifies new functionality around elicitations
  introduced in https://github.com/openai/codex/pull/1623 (and the fix
  introduced in https://github.com/openai/codex/pull/1629) by doing the
  following:
  
  - starts a mock model provider with canned responses for
  `/v1/chat/completions`
  - starts the MCP server with a `config.toml` to use that model provider
  (and `approval_policy = "untrusted"`)
  - sends the `codex` tool call which causes the mock model provider to
  request a shell call for `git init`
  - the MCP server sends an elicitation to the client to approve the
  request
  - the client replies to the elicitation with `"approved"`
  - the MCP server runs the command and re-samples the model, getting a
  `"finish_reason": "stop"`
  - in turn, the MCP server sends the final response to the original
  `codex` tool call
  - verifies that `git init` ran as expected
  
  To test:
  
  ```
  cargo test shell_command_approval_triggers_elicitation
  ```
  
  In writing this test, I discovered that `ExecApprovalResponse` does not
  conform to `ElicitResult`, so I added a TODO to fix that, since I think
  that should be updated in a separate PR. As it stands, this PR does not
  update any business logic, though it does make a number of members of
  the `mcp-server` crate `pub` so they can be used in the test.
  
  One additional learning from this PR is that
  `std::process::Command::cargo_bin()` from the `assert_cmd` trait is only
  available for `std::process::Command`, but we really want to use
  `tokio::process::Command` so that everything is async and we can
  leverage utilities like `tokio::time::timeout()`. The trick I came up
  with was to use `cargo_bin()` to locate the program, and then to use
  `std::process::Command::get_program()` when constructing the
  `tokio::process::Command`.

  Michael Bolin · 2025-07-21 10:27:07 -07:00
  d49d802b06
• fix: address review feedback on #1621 and #1623 (#1631)

  - formalizes `ExecApprovalElicitRequestParams`
  - adds some defensive logic when messages fail to parse
  - fixes a typo in a comment

  Michael Bolin · 2025-07-20 14:42:11 -07:00
  8a6c6cee88
• feat: leverage elicitations in the MCP server (#1623)

  This updates the MCP server so that if it receives an
  `ExecApprovalRequest` from the `Codex` session, it in turn sends an [MCP
  elicitation](https://modelcontextprotocol.io/specification/draft/client/elicitation)
  to the client to ask for the approval decision. Upon getting a response,
  it forwards the client's decision via `Op::ExecApproval`.
  
  Admittedly, we should be doing the same thing for
  `ApplyPatchApprovalRequest`, but this is our first time experimenting
  with elicitations, so I'm inclined to defer wiring that code path up
  until we feel good about how this one works.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/1623).
  * __->__ #1623
  * #1622
  * #1621
  * #1620

  Michael Bolin · 2025-07-19 01:32:03 -04:00
  018003e52f
• chore: introduce OutgoingMessageSender (#1622)

  Previous to this change, `MessageProcessor` had a
  `tokio::sync::mpsc::Sender<JSONRPCMessage>` as an abstraction for server
  code to send a message down to the MCP client. Because `Sender` is cheap
  to `clone()`, it was straightforward to make it available to tasks
  scheduled with `tokio::task::spawn()`.
  
  This worked well when we were only sending notifications or responses
  back down to the client, but we want to add support for sending
  elicitations in #1623, which means that we need to be able to send
  _requests_ to the client, and now we need a bit of centralization to
  ensure all request ids are unique.
  
  To that end, this PR introduces `OutgoingMessageSender`, which houses
  the existing `Sender<OutgoingMessage>` as well as an `AtomicI64` to mint
  out new, unique request ids. It has methods like `send_request()` and
  `send_response()` so that callers do not have to deal with
  `JSONRPCMessage` directly, as having to set the `jsonrpc` for each
  message was a bit tedious (this cleans up `codex_tool_runner.rs` quite a
  bit).
  
  We do not have `OutgoingMessageSender` implement `Clone` because it is
  important that the `AtomicI64` is shared across all users of
  `OutgoingMessageSender`. As such, `Arc<OutgoingMessageSender>` must be
  used instead, as it is frequently shared with new tokio tasks.
  
  As part of this change, we update `message_processor.rs` to embrace
  `await`, though we must be careful that no individual handler blocks the
  main loop and prevents other messages from being handled.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/1622).
  * #1623
  * __->__ #1622
  * #1621
  * #1620

  Michael Bolin · 2025-07-19 00:30:56 -04:00
  11fd3123be
• chore: support MCP schema 2025-06-18 (#1621)

  This updates the schema in `generate_mcp_types.py` from `2025-03-26` to
  `2025-06-18`, regenerates `mcp-types/src/lib.rs`, and then updates all
  the code that uses `mcp-types` to honor the changes.
  
  Ran
  
  ```
  npx @modelcontextprotocol/inspector just codex mcp
  ```
  
  and verified that I was able to invoke the `codex` tool, as expected.
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/1621).
  * #1623
  * #1622
  * __->__ #1621

  Michael Bolin · 2025-07-19 00:09:34 -04:00
  e78ec00e73
• feat: add codex_linux_sandbox_exe: Option<PathBuf> field to Config (#1089)

  https://github.com/openai/codex/pull/1086 is a work-in-progress to make
  Linux sandboxing work more like Seatbelt where, for the command we want
  to sandbox, we build up the command and then hand it, and some sandbox
  configuration flags, to another command to set up the sandbox and then
  run it.
  
  In the case of Seatbelt, macOS provides this helper binary and provides
  it at `/usr/bin/sandbox-exec`. For Linux, we have to build our own and
  pass it through (which is what #1086 does), so this makes the new
  `codex_linux_sandbox_exe` available on `Config` so that it will later be
  available in `exec.rs` when we need it in #1086.

  Michael Bolin · 2025-05-22 21:52:28 -07:00
  d1de7bb383
• Workspace lints and disallow unwrap (#855)

  Sets submodules to use workspace lints. Added denying unwrap as a
  workspace level lint, which found a couple of cases where we could have
  propagated errors. Also manually labeled ones that were fine by my eye.

  jcoens-openai · 2025-05-08 09:46:18 -07:00
  87cf120873
• Update cargo to 2024 edition (#842)

  Some effects of this change:
  - New formatting changes across many files. No functionality changes
  should occur from that.
  - Calls to `set_env` are considered unsafe, since this only happens in
  tests we wrap them in `unsafe` blocks

  jcoens-openai · 2025-05-07 08:37:48 -07:00
  8a89d3aeda
• feat: make Codex available as a tool when running it as an MCP server (#811)

  This PR replaces the placeholder `"echo"` tool call in the MCP server
  with a `"codex"` tool that calls Codex. Events such as
  `ExecApprovalRequest` and `ApplyPatchApprovalRequest` are not handled
  properly yet, but I have `approval_policy = "never"` set in my
  `~/.codex/config.toml` such that those codepaths are not exercised.
  
  The schema for this MPC tool is defined by a new `CodexToolCallParam`
  struct introduced in this PR. It is fairly similar to `ConfigOverrides`,
  as the param is used to help create the `Config` used to start the Codex
  session, though it also includes the `prompt` used to kick off the
  session.
  
  This PR also introduces the use of the third-party `schemars` crate to
  generate the JSON schema, which is verified in the
  `verify_codex_tool_json_schema()` unit test.
  
  Events that are dispatched during the Codex session are sent back to the
  MCP client as MCP notifications. This gives the client a way to monitor
  progress as the tool call itself may take minutes to complete depending
  on the complexity of the task requested by the user.
  
  In the video below, I launched the server via:
  
  ```shell
  mcp-server$ RUST_LOG=debug npx @modelcontextprotocol/inspector cargo run --
  ```
  
  In the video, you can see the flow of:
  
  * requesting the list of tools
  * choosing the **codex** tool
  * entering a value for **prompt** and then making the tool call
  
  Note that I left the other fields blank because when unspecified, the
  values in my `~/.codex/config.toml` were used:
  
  
  https://github.com/user-attachments/assets/1975058c-b004-43ef-8c8d-800a953b8192
  
  Note that while using the inspector, I did run into
  https://github.com/modelcontextprotocol/inspector/issues/293, though the
  tip about ensuring I had only one instance of the **MCP Inspector** tab
  open in my browser seemed to fix things.

  Michael Bolin · 2025-05-05 07:16:19 -07:00
  2b72d05c5e
• feat: introduce mcp-server crate (#792)

  This introduces the `mcp-server` crate, which contains a barebones MCP
  server that provides an `echo` tool that echoes the user's request back
  to them.
  
  To test it out, I launched
  [modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector)
  like so:
  
  ```
  mcp-server$ npx @modelcontextprotocol/inspector cargo run --
  ```
  
  and opened up `http://127.0.0.1:6274` in my browser:
  
  
  ![image](https://github.com/user-attachments/assets/83fc55d4-25c2-4497-80cd-e9702283ff93)
  
  I also had to make a small fix to `mcp-types`, adding
  `#[serde(untagged)]` to a number of `enum`s.

  Michael Bolin · 2025-05-02 17:25:58 -07:00
  21cd953dbd