Documentation 2026-09-10 16:58 UTC to 2026-09-11 20:00 UTC

119 href: "/codex/app-server",119 href: "/codex/app-server",

120 icon: "storage",120 icon: "storage",

121 },121 },

122 {

123 title: "MCP Server",

124 description:

125 "Expose Codex capabilities through Model Context Protocol.",

126 href: "/codex/mcp-server",

127 icon: "connect",

128 },

129 {122 {

130 title: "GitHub Action",123 title: "GitHub Action",

131 description: "Run Codex from GitHub Actions workflows.",124 description: "Run Codex from GitHub Actions workflows.",

34 34 

35Granting local Work access does not automatically approve every application, grant administrator rights, or bypass the permissions of the account used to reach another system. An approved shared connection can have different privileges from the user's personal account.35Granting local Work access does not automatically approve every application, grant administrator rights, or bypass the permissions of the account used to reach another system. An approved shared connection can have different privileges from the user's personal account.

36 36 

37Direct file reads, file edits, and shell commands follow the task's sandbox and approval settings. Computer Use accesses content through an approved native application under that application's permissions. A restriction on direct file access does not by itself establish the same restriction on files the application can open.

38 

37## Computer Use and application approvals39## Computer Use and application approvals

38 40 

39[Computer Use](https://learn.chatgpt.com/docs/computer-use) can interact with supported desktop applications only when the capability is available, the required operating-system permissions are granted, and the user authorizes the application. Depending on the available options, approval can apply to the current session or future tasks.41Workspace permissions determine who can use Work Local. Administrator policies can further restrict which native applications [Computer Use](https://learn.chatgpt.com/docs/computer-use) may operate and whether application approvals can be saved for future sessions. Required operating-system permissions and application approvals still apply. When a task uses an application or signed-in account, that account's permissions determine which information and actions are available.

42 

43Allowing an application through administrator policy does not install the required plugin, grant operating-system permissions, or approve an action that still requires review. For supported controls and configuration examples, see [Managed browser and Computer Use controls](https://learn.chatgpt.com/docs/enterprise/managed-configuration#control-browser-and-computer-use).

40 44 

41On macOS, Screen Recording allows Computer Use to see application content, and Accessibility allows it to click, type, and navigate. Supported macOS tasks can run in the background. On Windows, Computer Use operates on the active, visible desktop and cannot run in the background while the user continues using that same session.45On macOS, Screen Recording allows Computer Use to see application content, and Accessibility allows it to click, type, and navigate. Supported macOS tasks can run in the background. On Windows, Computer Use operates on the active, visible desktop and cannot run in the background while the user continues using that same session.

42 46 

44 48 

45### Locked devices49### Locked devices

46 50 

47Supported macOS configurations can optionally allow an approved Computer Use task to continue while the Mac is locked. Availability depends on the app version, feature rollout, applicable requirements, and remote-control eligibility.51Supported macOS configurations can optionally allow an approved Computer Use task to continue after the Mac locks. Availability depends on the app version, feature rollout, applicable requirements, and remote-control eligibility.

52 

53Enabling Locked Use installs a macOS authorization plugin that can temporarily unlock the Mac for an active, trusted Computer Use turn. ChatGPT covers every display during the temporary unlock. If it detects local keyboard or pointer input, it relocks the Mac and pauses automatic unlock until the user unlocks it manually. See [How Locked Use works](https://learn.chatgpt.com/docs/computer-use#locked-use).

48 54 

49Administrators can disable locked-device operation through supported managed configuration. Windows Computer Use requires an active, unlocked desktop; macOS locked-use behavior does not establish equivalent Windows support.55Administrators can prevent users from enabling Locked Use on managed Macs. This requirement does not turn off Locked Use if it is already enabled. Windows Computer Use requires an active, unlocked desktop. See [Locked Use restrictions](https://learn.chatgpt.com/docs/enterprise/managed-configuration#restrict-locked-computer-use).

50 56 

51## Browser sessions and existing sign-ins57## Browser sessions and existing sign-ins

52 58 

53Work Local does not automatically gain access to every browser or company account. Access depends on the browser used, the signed-in account, and the approvals required for that browser experience.59Work Local does not automatically gain access to every browser or company account. Access depends on the browser used, the signed-in account, and the approvals required for that browser experience.

54 60 

55| Browser path | Session and security boundary |61| Browser path | Session and security boundary |

56| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |62| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

57| [Desktop in-app browser](https://learn.chatgpt.com/docs/browser) | Uses a browser profile separate from the user's regular browser. The user can sign in within that profile, and supported website access may require approval. The built-in browser cannot automate file uploads. |63| [Desktop in-app browser](https://learn.chatgpt.com/docs/browser) | Uses a profile separate from the user's regular browser. Users can sign in within that profile. On supported clients, managed Browser Use policies restrict agent access to sites and available browser capabilities. The built-in browser cannot automate file uploads. |

58| [Chrome extension](https://learn.chatgpt.com/docs/chrome-extension) | Can interact with existing browser tabs and accounts when the extension and website access are approved. Users can approve a site once or allow future access; browser-history and local-file access require separate review. |64| [Chrome extension](https://learn.chatgpt.com/docs/chrome-extension) | Can interact with existing tabs and signed-in accounts when the extension and website access are approved. On supported clients, the same managed Browser Use policies apply to agent actions through the extension. |

59| Computer Use operating a browser | Uses a browser approved as a desktop application, including accounts already signed in to that browser. Operating-system permissions, application approval, and the existing account's permissions still apply. |65| Computer Use operating a browser | Operates the browser as an approved native application and can use accounts already signed in. **Browser Use's site and capability policies do not apply to this path.** Native-app policies, operating-system permissions, application approvals, and the signed-in account's permissions still apply. |

60 66 

61Website approval options and sensitive-action confirmations vary by browser experience. Allowing all sites reduces future approval prompts, so users should review that choice before enabling it.67Supported Browser Use policies can restrict site access, uploads, downloads, browser-history access, and full Chrome DevTools Protocol (CDP) access for browser debugging. Administrators can also restrict automatic approval review, saved approvals, and how long site-access approvals last. A user approval cannot override an administrator's denial. See [Managed browser controls](https://learn.chatgpt.com/docs/enterprise/managed-configuration#control-browser-and-computer-use).

62 68 

63A hosted cloud browser is separate from the user's local browsers and does not automatically inherit their existing sign-ins. Supported cloud workflows can request a separate, user-authorized sign-in.69A hosted cloud browser is separate from the user's local browsers and does not automatically inherit their existing sign-ins. Website sign-in through the cloud browser is not available in Enterprise or Edu workspaces.

64 70 

65## Apps, plugins, and connected accounts71## Apps, plugins, and connected accounts

66 72 

67A connected app can provide access to information or actions in another system. A plugin can use an app as an underlying tool. Making a plugin available does not automatically enable the required app, authorize an account, or permit every action.73A connected app can provide access to information or actions in another system. A plugin can use an app as an underlying tool. Making a plugin available does not automatically enable the required app, authorize an account, or permit every action.

68 74 

69Plugin and app availability depend on the workspace plan and configuration. The [ChatGPT Work overview](https://learn.chatgpt.com/docs/enterprise/chatgpt-work-overview) describes plugins and their underlying apps as off by default for Enterprise and Edu workspaces and on by default for Business workspaces. Verify the actual settings for the relevant workspace and product experience.75Plugin and app defaults depend on the plan and whether the workspace is new or existing. New Enterprise and Edu workspaces start with a selected set of apps enabled; those defaults do not change existing workspace settings and do not apply to Healthcare workspaces. In general, new plugins and apps are disabled by default in Enterprise and Edu. Business apps are enabled by default. Administrators can change availability. See the [current plugin and app defaults](https://help.openai.com/en/articles/11509118) and the [ChatGPT Work overview](https://learn.chatgpt.com/docs/enterprise/chatgpt-work-overview).

70 76 

71Before a task uses a connected system, confirm that the workspace allows the app and any required plugin, the connection is authorized, and the connected account can access the requested information or action. Read-only settings, allowed actions, and confirmation requirements vary by integration.77Before a task uses a connected system, confirm that the workspace allows the app and any required plugin, the connection is authorized, and the connected account can access the requested information or action. Read-only settings, allowed actions, and confirmation requirements vary by integration.

72 78 

73Desktop-only plugins, local tools, and other locally provided capabilities can follow different installation or approval paths. Do not assume that every local tool uses the same administrative approval process.79Plugins that provide browser or Computer Use capabilities require their own availability and installation review. Making a plugin available does not override managed browser or native-app policies, operating-system permissions, or required approvals. Desktop-only plugins and locally provided tools may follow different installation paths. See [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors).

74 80 

75### Personal and shared connections81### Personal and shared connections

76 82 

88 94 

89Enforced requirements cannot be overridden by individual users. Managed defaults, by contrast, establish initial settings that users may be able to change. Neither replaces workspace roles or operating-system permissions.95Enforced requirements cannot be overridden by individual users. Managed defaults, by contrast, establish initial settings that users may be able to change. Neither replaces workspace roles or operating-system permissions.

90 96 

97Supported local clients load managed requirements during configuration loading. A background refresh can make newer cloud-managed requirements available for a later configuration load; it does not by itself demonstrate that an existing task is using the new policy. macOS MDM requirement changes are read at the next client launch. After changing managed requirements, restart the applicable local client and verify its effective settings before relying on the restriction. Workspace permission changes can follow a different activation path. See [How local clients apply cloud-managed requirements](https://learn.chatgpt.com/docs/enterprise/managed-configuration#how-local-clients-apply-cloud-managed-requirements).

98 

91| Managed setting | Security purpose |99| Managed setting | Security purpose |

92| ----------------------------------------------------- | ---------------------------------------------------------------------------- |100| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |

93| `features.computer_use = false` | Disable supported Computer Use capabilities. |101| `features.computer_use = false` | Disable native Computer Use capabilities. |

94| `allow_appshots = false` | Prevent supported Appshot capture. |102| `allow_appshots = false` | Prevent supported Appshot capture. |

95| `features.in_app_browser = false` | Disable the desktop app's built-in browser. |103| `features.in_app_browser = false` | Disable the desktop app's built-in browser. |

96| `features.browser_use = false` | Disable supported browser automation; review other browser paths separately. |104| `features.browser_use = false` | Disable supported Browser Use capabilities; external Browser Use has a separate flag. |

105| `features.browser_use_external = false` | Disable agent-driven Browser Use through supported browser extensions. |

97| `features.apps = false` or `features.plugins = false` | Restrict supported connected applications or plugins. |106| `features.apps = false` or `features.plugins = false` | Restrict supported connected applications or plugins. |

98| `computer_use.allow_locked_computer_use = false` | Prevent supported Computer Use while a Mac is locked. |107| `computer_use.allow_locked_computer_use = false` | Prevent users from enabling Locked Use on managed Macs; does not disable existing Locked Use. |

108 

109These are restriction examples, not a list of enabled defaults. Omitting a feature requirement leaves normal client, platform, rollout, and user settings in effect. Browser Use feature flags, the built-in browser pane, and native Computer Use are separate controls; validate each browser path independently.

99 110 

100Available settings and delivery methods depend on the client, operating system, workspace, and deployment configuration. Validate restrictions on a representative managed device. For supported policy settings, configuration examples, and MDM setup instructions, see [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).111Available settings and delivery methods depend on the client, operating system, workspace, and deployment configuration. Validate restrictions on a representative managed device. For supported policy settings, configuration examples, and MDM setup instructions, see [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).

101 112 

102## Local networking and private resources113## Local networking and private resources

103 114 

104A task can reach company information through paths such as a device browser, an approved desktop application, or a connected app. Existing device, proxy, VPN, source-system, and endpoint controls may apply differently to each path.115Work Local can reach company information through a browser, a native application, a connected app, or another supported tool. Network controls apply differently to each path, and access to a corporate VPN does not itself authorize a task to use an internal resource.

105 116 

106Access to a corporate VPN does not automatically authorize every tool to use every internal resource. Likewise, a cloud Work browser or cloud-network control is not a universal restriction on local device networking. Review the actual connection, identity, destination, and action required by the workflow.117Managed network requirements and Browser Use origin policies are separate checks. Validate both on the app versions and operating systems in your deployment before relying on a network restriction to limit Browser Use. Browser policy checks do not mean browser traffic is routed through the command-network proxy, and Browser Use policies do not govern traffic from native applications.

118 

119Managed network requirements under `[experimental_network]` are experimental and may change. Windows support is limited; test the exact client and environment before applying them to Windows users. Domain rules alone do not activate the managed proxy; `experimental_network.enabled = true` is required and does not override a sandbox that keeps networking off.

120 

121Review the connection, signed-in account, destination, and action required by the workflow. For configuration details and platform limitations, see [Network access requirements](https://learn.chatgpt.com/docs/enterprise/managed-configuration#configure-network-access-requirements).

107 122 

108## Data handling and retention123## Data handling and retention

109 124 

129 144 

130Available reporting depends on the workspace plan, product experience, event, connected application, and deployed configuration. Verify Work Local coverage before relying on a workspace export for incident response or regulatory review.145Available reporting depends on the workspace plan, product experience, event, connected application, and deployed configuration. Verify Work Local coverage before relying on a workspace export for incident response or regulatory review.

131 146 

147In supported versions, Browser Use can emit OpenTelemetry events for capability checks, including site access, uploads, and downloads. These events record the decision and decision source, with policy details where available. The decision source can be unknown. When export is configured, they are sent to the customer's OpenTelemetry endpoint alongside other local-runtime telemetry.

148 

149OpenTelemetry export is separate from Compliance API records and must be configured independently. These events do not establish a complete record of every browser or native-app action. See [OpenTelemetry configuration](https://learn.chatgpt.com/docs/config-file/config-advanced#observability-and-telemetry).

150 

132Determine whether the relevant systems record the task identity, supported prompts and responses, connected-app calls, browser approvals, application actions, local file activity, or endpoint events. Source-system and device records can provide different visibility from ChatGPT workspace records.151Determine whether the relevant systems record the task identity, supported prompts and responses, connected-app calls, browser approvals, application actions, local file activity, or endpoint events. Source-system and device records can provide different visibility from ChatGPT workspace records.

133 152 

134OpenAI does not store a separate complete record of Chrome actions performed through the extension. Do not assume that every local file operation, screenshot, browser action, approval, or external update appears in the Compliance API.153OpenAI does not store a separate complete record of Chrome actions performed through the extension. Do not assume that every local file operation, screenshot, browser action, approval, or external update appears in the Compliance API.

295| `codex app-server` | Supported. Configure WIF on the app-server host, not on a remote client. |295| `codex app-server` | Supported. Configure WIF on the app-server host, not on a remote client. |

296| `codex exec-server --remote` | Supported for authentication to the remote environment registry. Configure WIF on the exec-server host. |296| `codex exec-server --remote` | Supported for authentication to the remote environment registry. Configure WIF on the exec-server host. |

297| Local exec-server process operations | Do not use WIF authentication. They run through the local exec-server protocol. |297| Local exec-server process operations | Do not use WIF authentication. They run through the local exec-server protocol. |

298| `codex mcp-server` | Not supported. |

299 298 

300Remote app-server and exec-server clients never send the upstream identity299Remote app-server and exec-server clients never send the upstream identity

301token over their protocols.300token over their protocols.

1# Use Codex with the Agents SDK1# Codex MCP server removal

2 2 

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5# Running Codex as an MCP server5The `codex mcp-server` command and the standalone `codex-mcp-server` binary have

6been removed. Integrations that launch either command must migrate before

7upgrading Codex. The previous MCP tool reference and Agents SDK examples on this

8page are no longer supported.

6 9 

7`codex mcp-server` is deprecated. Use the [Codex app10## Use the Codex app server

8 server](https://learn.chatgpt.com/docs/app-server) instead. To call Codex from Claude Code, use the

9 [Codex plugin for Claude Code](https://github.com/openai/codex-plugin-cc),

10 which uses the app server. This page documents the deprecated command for

11 existing integrations.

12 11 

13You can run Codex as an MCP server and connect it from other MCP clients (for example, an agent built with the [OpenAI Agents SDK MCP integration](https://developers.openai.com/api/docs/guides/agents/integrations-observability#mcp)).12Use the [Codex app server](https://learn.chatgpt.com/docs/app-server) for integrations that need

13authentication, conversation history, approvals, and streamed agent events.

14 14 

15To start Codex as an MCP server, you can use the following command:15The app server uses its own [JSON-RPC protocol](https://learn.chatgpt.com/docs/app-server#protocol). It

16isn't an MCP server or a drop-in replacement for an MCP client: update your

17integration to use the app-server protocol instead of MCP tool calls.

18The app-server command is experimental and isn't supported for production

19workloads.

16 20 

17```bash21## Connect Codex to MCP tools

18codex mcp-server

19```

20 22 

21You can launch a Codex MCP server with the [Model Context Protocol Inspector](https://modelcontextprotocol.io/legacy/tools/inspector):23Codex continues to support [external MCP servers](https://learn.chatgpt.com/docs/extend/mcp).

22 24Use `codex mcp` to manage those connections. The removal affects hosting Codex

23```bash25as an MCP server.

24npx @modelcontextprotocol/inspector codex mcp-server

25```

26 

27Send a `tools/list` request to see two tools:

28 

29**`codex`**: Run a Codex session with the following prompt and configuration overrides:

30 

31| Property | Type | Description |

32| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |

33| **`prompt`** (required) | `string` | The initial user prompt to start the Codex conversation. |

34| `approval-policy` | `string` | Approval policy for shell commands generated by the model: `on-request` or `never`. |

35| `base-instructions` | `string` | The set of instructions to use instead of the default ones. |

36| `compact-prompt` | `string` | Prompt used when compacting the conversation. |

37| `config` | `object` | Individual configuration settings that override what's in `$CODEX_HOME/config.toml`. |

38| `cwd` | `string` | Working directory for the session. If relative, resolved against the server process's current directory. |

39| `developer-instructions` | `string` | Developer instructions injected as a developer-role message. |

40| `model` | `string` | Optional override for the model name (for example, `gpt-5.6-terra`). |

41| `sandbox` | `string` | Sandbox mode: `read-only`, `workspace-write`, or `danger-full-access`. |

42 

43**`codex-reply`**: Continue a Codex session by providing the thread ID and prompt. The `codex-reply` tool takes these properties:

44 

45| Property | Type | Description |

46| ----------------------------- | ------ | --------------------------------------------------------- |

47| **`prompt`** (required) | string | The next user prompt to continue the Codex conversation. |

48| **`threadId`** (required) | string | The ID of the thread to continue. |

49| `conversationId` (deprecated) | string | Deprecated alias for `threadId` (kept for compatibility). |

50 

51Use the `threadId` from `structuredContent.threadId` in the `tools/call` response. Approval prompts (exec/patch) also include `threadId` in their `params` payload.

52 

53Example response payload:

54 

55```json

56{

57 "structuredContent": {

58 "threadId": "019bbb20-bff6-7130-83aa-bf45ab33250e",

59 "content": "`ls -lah` (or `ls -alh`) — long listing, includes dotfiles, human-readable sizes."

60 },

61 "content": [

62 {

63 "type": "text",

64 "text": "`ls -lah` (or `ls -alh`) — long listing, includes dotfiles, human-readable sizes."

65 }

66 ]

67}

68```

69 

70Note modern MCP clients generally report only `"structuredContent"` as the result of a tool call, if present, though the Codex MCP server also returns `"content"` for the benefit of older MCP clients.

71 

72# Creating multi-agent workflows

73 

74Codex CLI can do far more than run ad-hoc tasks. By exposing the CLI as a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server and orchestrating it with the OpenAI Agents SDK, you can create deterministic, reviewable workflows that scale from a single agent to a complete software delivery pipeline.

75 

76This guide walks through the same workflow showcased in the [OpenAI Cookbook](https://github.com/openai/openai-cookbook/blob/main/examples/codex/codex_mcp_agents_sdk/building_consistent_workflows_codex_cli_agents_sdk.ipynb). You will:

77 

78- launch Codex CLI as a long-running MCP server,

79- build a focused single-agent workflow that produces a playable browser game, and

80- orchestrate a multi-agent team with hand-offs, guardrails, and full traces you can review afterwards.

81 

82Before starting, make sure you have:

83 

84- [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) installed locally so the `codex` command is available.

85- Python 3.10+ with `pip`.

86- Node.js 18+ if you want to run the MCP Inspector example above.

87- An OpenAI API key stored locally. You can create or manage keys in the [OpenAI dashboard](https://platform.openai.com/account/api-keys).

88 

89Create a working directory for the guide and add your API key to a `.env` file:

90 

91```bash

92mkdir codex-workflows

93cd codex-workflows

94printf "OPENAI_API_KEY=sk-..." > .env

95```

96 

97## Install dependencies

98 

99The Agents SDK handles orchestration across Codex, hand-offs, and traces. Install the latest SDK packages:

100 

101```bash

102python -m venv .venv

103source .venv/bin/activate

104pip install --upgrade openai openai-agents python-dotenv

105```

106 

107Activating a virtual environment keeps the SDK dependencies isolated from the

108 rest of your system.

109 

110## Initialize Codex CLI as an MCP server

111 

112Start by turning Codex CLI into an MCP server that the Agents SDK can call. The server exposes two tools (`codex()` to start a conversation and `codex-reply()` to continue one) and keeps Codex alive across multiple agent turns.

113 

114Create a file called `codex_mcp.py` and add the following:

115 

116```python

117import asyncio

118 

119from agents import Agent, Runner

120from agents.mcp import MCPServerStdio

121 

122 

123async def main() -> None:

124 async with MCPServerStdio(

125 name="Codex CLI",

126 params={

127 "command": "codex",

128 "args": ["mcp-server"],

129 },

130 client_session_timeout_seconds=360000,

131 ) as codex_mcp_server:

132 print("Codex MCP server started.")

133 # More logic coming in the next sections.

134 return

135 

136 

137if __name__ == "__main__":

138 asyncio.run(main())

139```

140 

141Run the script once to verify that Codex launches successfully:

142 

143```bash

144python codex_mcp.py

145```

146 

147The script exits after printing `Codex MCP server started.`. In the next sections you will reuse the same MCP server inside richer workflows.

148 

149## Build a single-agent workflow

150 

151Let’s start with a scoped example that uses Codex MCP to ship a small browser game. The workflow relies on two agents:

152 

1531. **Game Designer**: writes a brief for the game.

1542. **Game Developer**: implements the game by calling Codex MCP.

155 

156Update `codex_mcp.py` with the following code. It keeps the MCP server setup from above and adds both agents.

157 

158```python

159import asyncio

160import os

161 

162from dotenv import load_dotenv

163 

164from agents import Agent, Runner, set_default_openai_api

165from agents.mcp import MCPServerStdio

166 

167load_dotenv(override=True)

168set_default_openai_api(os.getenv("OPENAI_API_KEY"))

169 

170 

171async def main() -> None:

172 async with MCPServerStdio(

173 name="Codex CLI",

174 params={

175 "command": "codex",

176 "args": ["mcp-server"],

177 },

178 client_session_timeout_seconds=360000,

179 ) as codex_mcp_server:

180 developer_agent = Agent(

181 name="Game Developer",

182 instructions=(

183 "You are an expert in building simple games using basic html + css + javascript with no dependencies. "

184 "Save your work in a file called index.html in the current directory. "

185 "Always call codex with \"approval-policy\": \"never\" and \"sandbox\": \"workspace-write\"."

186 ),

187 mcp_servers=[codex_mcp_server],

188 )

189 

190 designer_agent = Agent(

191 name="Game Designer",

192 instructions=(

193 "You are an indie game connoisseur. Come up with an idea for a single page html + css + javascript game that a developer could build in about 50 lines of code. "

194 "Format your request as a 3 sentence design brief for a game developer and call the Game Developer coder with your idea."

195 ),

196 model="gpt-5",

197 handoffs=[developer_agent],

198 )

199 

200 await Runner.run(designer_agent, "Implement a fun new game!")

201 

202 

203if __name__ == "__main__":

204 asyncio.run(main())

205```

206 

207Execute the script:

208 

209```bash

210python codex_mcp.py

211```

212 

213Codex will read the designer's brief, create an `index.html` file, and write the full game to disk. Open the generated file in a browser to play the result. Every run produces a different design with unique play-style twists and polish.

214 

215## Expand to a multi-agent workflow

216 

217Now turn the single-agent setup into an orchestrated, traceable workflow. The system adds:

218 

219- **Project Manager**: creates shared requirements, coordinates hand-offs, and enforces guardrails.

220- **Designer**, **Frontend Developer**, **Server Developer**, and **Tester**: each with scoped instructions and output folders.

221 

222Create a new file called `multi_agent_workflow.py`:

223 

224```python

225import asyncio

226import os

227 

228from dotenv import load_dotenv

229 

230from agents import (

231 Agent,

232 ModelSettings,

233 Runner,

234 WebSearchTool,

235 set_default_openai_api,

236)

237from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

238from agents.mcp import MCPServerStdio

239from openai.types.shared import Reasoning

240 

241load_dotenv(override=True)

242set_default_openai_api(os.getenv("OPENAI_API_KEY"))

243 

244 

245async def main() -> None:

246 async with MCPServerStdio(

247 name="Codex CLI",

248 params={"command": "codex", "args": ["mcp-server"]},

249 client_session_timeout_seconds=360000,

250 ) as codex_mcp_server:

251 designer_agent = Agent(

252 name="Designer",

253 instructions=(

254 f"""{RECOMMENDED_PROMPT_PREFIX}"""

255 "You are the Designer.\n"

256 "Your only source of truth is AGENT_TASKS.md and REQUIREMENTS.md from the Project Manager.\n"

257 "Do not assume anything that is not written there.\n\n"

258 "You may use the internet for additional guidance or research."

259 "Deliverables (write to /design):\n"

260 "- design_spec.md – a single page describing the UI/UX layout, main screens, and key visual notes as requested in AGENT_TASKS.md.\n"

261 "- wireframe.md – a simple text or ASCII wireframe if specified.\n\n"

262 "Keep the output short and implementation-friendly.\n"

263 "When complete, handoff to the Project Manager with transfer_to_project_manager."

264 "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."

265 ),

266 model="gpt-5",

267 tools=[WebSearchTool()],

268 mcp_servers=[codex_mcp_server],

269 )

270 

271 frontend_developer_agent = Agent(

272 name="Frontend Developer",

273 instructions=(

274 f"""{RECOMMENDED_PROMPT_PREFIX}"""

275 "You are the Frontend Developer.\n"

276 "Read AGENT_TASKS.md and design_spec.md. Implement exactly what is described there.\n\n"

277 "Deliverables (write to /frontend):\n"

278 "- index.html – main page structure\n"

279 "- styles.css or inline styles if specified\n"

280 "- main.js or game.js if specified\n\n"

281 "Follow the Designer’s DOM structure and any integration points given by the Project Manager.\n"

282 "Do not add features or branding beyond the provided documents.\n\n"

283 "When complete, handoff to the Project Manager with transfer_to_project_manager_agent."

284 "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."

285 ),

286 model="gpt-5",

287 mcp_servers=[codex_mcp_server],

288 )

289 

290 backend_developer_agent = Agent(

291 name="Backend Developer",

292 instructions=(

293 f"""{RECOMMENDED_PROMPT_PREFIX}"""

294 "You are the Backend Developer.\n"

295 "Read AGENT_TASKS.md and REQUIREMENTS.md. Implement the backend endpoints described there.\n\n"

296 "Deliverables (write to /backend):\n"

297 "- package.json – include a start script if requested\n"

298 "- server.js – implement the API endpoints and logic exactly as specified\n\n"

299 "Keep the code as simple and readable as possible. No external database.\n\n"

300 "When complete, handoff to the Project Manager with transfer_to_project_manager_agent."

301 "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."

302 ),

303 model="gpt-5",

304 mcp_servers=[codex_mcp_server],

305 )

306 

307 tester_agent = Agent(

308 name="Tester",

309 instructions=(

310 f"""{RECOMMENDED_PROMPT_PREFIX}"""

311 "You are the Tester.\n"

312 "Read AGENT_TASKS.md and TEST.md. Verify that the outputs of the other roles meet the acceptance criteria.\n\n"

313 "Deliverables (write to /tests):\n"

314 "- TEST_PLAN.md – bullet list of manual checks or automated steps as requested\n"

315 "- test.sh or a simple automated script if specified\n\n"

316 "Keep it minimal and easy to run.\n\n"

317 "When complete, handoff to the Project Manager with transfer_to_project_manager."

318 "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."

319 ),

320 model="gpt-5",

321 mcp_servers=[codex_mcp_server],

322 )

323 

324 project_manager_agent = Agent(

325 name="Project Manager",

326 instructions=(

327 f"""{RECOMMENDED_PROMPT_PREFIX}"""

328 """

329 You are the Project Manager.

330 

331 Objective:

332 Convert the input task list into three project-root files the team will execute against.

333 

334 Deliverables (write in project root):

335 - REQUIREMENTS.md: concise summary of product goals, target users, key features, and constraints.

336 - TEST.md: tasks with [Owner] tags (Designer, Frontend, Backend, Tester) and clear acceptance criteria.

337 - AGENT_TASKS.md: one section per role containing:

338 - Project name

339 - Required deliverables (exact file names and purpose)

340 - Key technical notes and constraints

341 

342 Process:

343 - Resolve ambiguities with minimal, reasonable assumptions. Be specific so each role can act without guessing.

344 - Create files using Codex MCP with {"approval-policy":"never","sandbox":"workspace-write"}.

345 - Do not create folders. Only create REQUIREMENTS.md, TEST.md, AGENT_TASKS.md.

346 

347 Handoffs (gated by required files):

348 1) After the three files above are created, hand off to the Designer with transfer_to_designer_agent and include REQUIREMENTS.md and AGENT_TASKS.md.

349 2) Wait for the Designer to produce /design/design_spec.md. Verify that file exists before proceeding.

350 3) When design_spec.md exists, hand off in parallel to both:

351 - Frontend Developer with transfer_to_frontend_developer_agent (provide design_spec.md, REQUIREMENTS.md, AGENT_TASKS.md).

352 - Backend Developer with transfer_to_backend_developer_agent (provide REQUIREMENTS.md, AGENT_TASKS.md).

353 4) Wait for Frontend to produce /frontend/index.html and Backend to produce /backend/server.js. Verify both files exist.

354 5) When both exist, hand off to the Tester with transfer_to_tester_agent and provide all prior artifacts and outputs.

355 6) Do not advance to the next handoff until the required files for that step are present. If something is missing, request the owning agent to supply it and re-check.

356 

357 PM Responsibilities:

358 - Coordinate all roles, track file completion, and enforce the above gating checks.

359 - Do NOT respond with status updates. Just handoff to the next agent until the project is complete.

360 """

361 ),

362 model="gpt-5",

363 model_settings=ModelSettings(

364 reasoning=Reasoning(effort="medium"),

365 ),

366 handoffs=[designer_agent, frontend_developer_agent, backend_developer_agent, tester_agent],

367 mcp_servers=[codex_mcp_server],

368 )

369 

370 designer_agent.handoffs = [project_manager_agent]

371 frontend_developer_agent.handoffs = [project_manager_agent]

372 backend_developer_agent.handoffs = [project_manager_agent]

373 tester_agent.handoffs = [project_manager_agent]

374 

375 task_list = """

376Goal: Build a tiny browser game to showcase a multi-agent workflow.

377 

378High-level requirements:

379- Single-screen game called "Bug Busters".

380- Player clicks a moving bug to earn points.

381- Game ends after 20 seconds and shows final score.

382- Optional: submit score to a simple backend and display a top-10 leaderboard.

383 

384Roles:

385- Designer: create a one-page UI/UX spec and basic wireframe.

386- Frontend Developer: implement the page and game logic.

387- Backend Developer: implement a minimal API (GET /health, GET/POST /scores).

388- Tester: write a quick test plan and a simple script to verify core routes.

389 

390Constraints:

391- No external database—memory storage is fine.

392- Keep everything readable for beginners; no frameworks required.

393- All outputs should be small files saved in clearly named folders.

394"""

395 

396 result = await Runner.run(project_manager_agent, task_list, max_turns=30)

397 print(result.final_output)

398 

399 

400if __name__ == "__main__":

401 asyncio.run(main())

402```

403 

404Run the script and watch the generated files:

405 

406```bash

407python multi_agent_workflow.py

408ls -R

409```

410 

411The project manager agent writes `REQUIREMENTS.md`, `TEST.md`, and `AGENT_TASKS.md`, then coordinates hand-offs across the designer, frontend, server, and tester agents. Each agent writes scoped artifacts in its own folder before handing control back to the project manager.

412 

413## Trace the workflow

414 

415Codex automatically records traces that capture every prompt, tool call, and hand-off. After the multi-agent run completes, open the [Traces dashboard](https://platform.openai.com/trace) to inspect the execution timeline.

416 

417The high-level trace highlights how the project manager verifies hand-offs before moving forward. Click into individual steps to see prompts, Codex MCP calls, files written, and execution durations. These details make it straightforward to audit every hand-off and understand how the workflow evolved turn by turn.

418These traces make it straightforward to debug workflow hiccups, audit agent behavior, and measure performance over time without requiring extra instrumentation.

13 13 

14Use the Codex SDK to automate coding tasks, including jobs in CI. Use the [Codex app server](https://learn.chatgpt.com/docs/app-server) to build custom clients that handle authentication, conversation history, approvals, and streamed agent events.14Use the Codex SDK to automate coding tasks, including jobs in CI. Use the [Codex app server](https://learn.chatgpt.com/docs/app-server) to build custom clients that handle authentication, conversation history, approvals, and streamed agent events.

15 15 

16`codex mcp-server` is deprecated. The [MCP server guide](https://learn.chatgpt.com/docs/mcp-server) remains available for existing integrations.16The `codex mcp-server` command and standalone `codex-mcp-server` binary have been removed. Use the [Codex app server](https://learn.chatgpt.com/docs/app-server) for existing integrations.

17 17 

18If you have beta access and need repository or change scans with structured18If you have beta access and need repository or change scans with structured

19security findings and coverage, use the [Codex Security TypeScript19security findings and coverage, use the [Codex Security TypeScript

4 4 

5Use this changelog to see what changed in the Codex Security plugin.5Use this changelog to see what changed in the Codex Security plugin.

6 6 

7**Latest plugin version:** `0.1.20`.7**Latest plugin version:** `0.1.24`.

8 8 

9Check the plugin version in your current Codex environment before you use a9Check the plugin version in your current Codex environment before you use a

10feature from a newer release.10feature from a newer release.

13SDK users can run `npx @openai/codex-security info --json` to check the13SDK users can run `npx @openai/codex-security info --json` to check the

14package and bundled plugin versions together.14package and bundled plugin versions together.

15 15 

16## 0.1.24 (September 9, 2026)

17 

18### Check Daybreak access from the plugin

19 

20- Check Daybreak access before a scan in desktop and CLI sessions signed in

21 with ChatGPT, without connecting the separate Codex Security Access app.

22- Show an enrollment link when access isn't granted, or a warning when access

23 can't be verified. Sessions that use only an API key can't verify account

24 access.

25- Continue the scan after the advisory, including when access is unavailable

26 or the check fails. The advisory doesn't grant access or control whether

27 the scan runs.

28 

29### Verify security fixes when requested

30 

31- Run `$codex-security:verify-fix` only when you explicitly request verification

32 of a security fix.

33- Keep ordinary fix implementation, code review, and test requests in their

34 existing workflows instead of automatically switching to the verification

35 result format.

36 

37## 0.1.23 (September 8, 2026)

38 

39### Assess the risk of a proposed patch

40 

41- Use `$codex-security:assess-patch-risk` to review a proposed change against

42 exact revisions and source evidence.

43- Assess impact, likelihood, and the difficulty of recovery separately from

44 regression protection, and identify evidence gaps that affect the recommendation.

45- Receive an advisory recommendation to merge, revise, or make no change.

46 The assessment doesn't merge code or replace repository approval rules.

47 

48### Recover retained results from failed scans

49 

50- Recover valid saved findings from a selected failed scan when you request

51 it, without repeating the scan.

52- Browse saved scans and findings without automatically recovering every

53 failed scan. Recovery preserves the failed outcome and isn't available for

54 running, completed, or canceled scans.

55- Preserve distinct findings when workers reuse candidate identifiers, and

56 keep valid evidence and root-cause details during recovery.

57 

58### Make scan setup and reports clearer

59 

60- See individual readiness checks and their blocking or warning details in

61 standard and change scans.

62- Keep a scan available for continuation while you decide how to resolve a

63 setup issue. Persistent configuration changes in interactive sessions still

64 require your approval.

65- See the configured include and exclude paths in deep-scan reports.

66- Keep context updates scoped to the selected scan without replacing saved

67 workspace defaults.

68 

69### Improve startup and GitHub triage

70 

71- Allow up to two minutes for the plugin's tool server to start, and pass

72 OpenAI API-key authentication to deep-scan workers.

73- Honor an explicitly selected GitHub connector when importing findings for

74 triage, and ask before switching to another connection or account.

75 

76## 0.1.22 (August 25, 2026)

77 

78### Verify existing security fixes

79 

80- Use `$codex-security:verify-fix` to check whether an existing patch resolves

81 a reported security finding without changing repository files or issue

82 trackers.

83- Receive a `fixed`, `still_vulnerable`, or `inconclusive` result for each

84 finding, with supporting evidence and validation limits.

85- Add an investigation before patching and a review after patching to the

86 finding-remediation workflow.

87 

88### Preserve findings when scans stop

89 

90- Save findings and pending candidates as deep-scan workers make progress.

91- Keep accepted worker findings represented when later result consolidation

92 omits them or fails.

93- Keep valid results from failed, canceled, or interrupted scans while

94 preserving their non-success outcome and incomplete coverage.

95- Carry the supplied scan prompt into deep-scan workers, and preserve supported

96 filesystem deny rules from the parent session.

97 

98### Improve Windows and filesystem compatibility

99 

100- Match equivalent Windows paths in scan history and load Windows system

101 configuration from the expected location.

102- Block scan artifact paths that Windows would interpret ambiguously.

103- Save scan results on filesystems that don't support hard links.

104- Read UTC scan timestamps consistently on Python 3.10.

105 

106## 0.1.21 (August 21, 2026)

107 

108### Install and start the plugin more reliably

109 

110- Install the plugin without requiring the optional Codex Security Access app.

111 The hosted access check remains advisory.

112- Use Codex's bundled Node.js runtime when starting the plugin, including on

113 Windows installations where packaged executables can't run directly.

114- Read Git metadata as UTF-8 on Windows.

115 

116### Preserve finding details and improve SARIF exports

117 

118- Keep validation, attack-path evidence, and root-cause details consistent

119 across saved findings, reports, and the Security workbench.

120- Export readable rule names, remediation guidance, CWE tags, and security

121 severity for GitHub code scanning while preserving finding identities,

122 fingerprints, and source locations.

123 

16## 0.1.20 (August 17, 2026)124## 0.1.20 (August 17, 2026)

17 125 

18### Run deep scans as complete independent audits126### Run deep scans as complete independent audits