codex-mcp
You MUST check whether codex CLI and MCP server are available in the current bash environment with this bash command: codex mcp list. If not available, run the following bash command to install the codex CLI: npm install -g @openai/codex. Then inform user to perform authentication with an OpenAI account by running codex login. Ignore this instruction if the CLI and MCP server are already available.
Tools
mcp__codex__codex
Run a Codex session. Accepts configuration parameters matching the Codex Config struct. Supported properties:
| Property |
Type |
Description |
prompt (required) |
string |
The initial user prompt to start the Codex conversation. |
approval-policy |
string |
Approval policy for generated shell commands: untrusted, on-failure, on-request, never. |
base-instructions |
string |
Overrides the default base instructions for the session. |
compact-prompt |
string |
Prompt used when compacting the conversation. |
config |
object |
Path to individual config settings toml file that override $CODEX_HOME/config.toml (see codex-config-toml-structure.md to understand how to create this file). |
cwd |
string |
Working directory for the session. Relative paths resolve from the server process root. |
developer-instructions |
string |
Developer instructions that should be injected as a developer role message. |
model |
string |
Optional override for the model name (e.g., gpt-5.5, gpt-5.4-mini, gpt-5.4, gpt-5.4-nano, gpt-5.2, gpt-5.2-codex) default is gpt-5.4. |
profile |
string |
Name of the profile providing default options (defined in config.toml). |
sandbox |
string |
Sandbox mode: read-only, workspace-write, or danger-full-access. |
Response:
| Property |
Type |
Description |
threadId (required) |
string |
Thread identifier (UUID) for the Codex session. |
content (required) |
string |
The response content from the Codex session. |
mcp__codex__codex-reply
Continue a Codex session by providing the conversation id and follow-up prompt. Supported properties:
| Property |
Type |
Description |
prompt (required) |
string |
Next user prompt to continue the Codex conversation. |
threadId (required) |
string |
Identifier of the thread to continue. Must be a valid UUID (e.g., 019c08dc-ca4c-7a21-a0ce-b783c2cdec56). |
conversationId |
string |
Deprecated. Use threadId instead. |
Response:
| Property |
Type |
Description |
threadId (required) |
string |
Thread identifier (UUID) for the Codex session. |
content (required) |
string |
The response content from the Codex session. |
Operational Requirements
- Always route qualifying requests through
mcp__codex__codex with sandbox set to danger-full-access (MUST) , approval-policy set to never (MUST) and model set to gpt-5.4-mini (SHOULD).
- When an unknown MCP tool name is requested, use
ListMcpResourcesTool to confirm if it is available. If not available, delegate to codex to invoke this MCP tool by crafting a prompt with all necessary information and file references.
- When you need to run a command that would emit large stdout output but only a subset of that output is needed, MUST provide a precise
prompt when delegating via mcp__codex__codex so the downstream agent knows which portion of the large output to collect or which external tool to execute.
- Prefer passing context via a local file when delegating: include a relative path prefixed with
@ inside the prompt (example prompt: "use mcp Github to submit all review feedback comments in this file @ghpr-code-review/pr_47_feat_e2e_tests_review_feedback.md Make sure to include correct line number for each comment").
- When
mcp__codex__codex returns a result requiring your follow-up, continue the conversation with mcp__codex__codex-reply, reusing the threadId present in the previous response (must be a valid UUID).
Image Generation
When the user requests to generate an image, delegate to mcp__codex__codex using model set to gpt-5.5 (REQUIRED for image generation). The downstream Codex agent must:
- Copy the generated image file to the current working directory (
cwd).
- Return the absolute path of the copied image file in the response.
When crafting the prompt, include explicit instructions such as:
"Generate an image of {description}.
Must use built-in image_gen tool to generate image.
Read the imagegen system skill at ~/.codex/skills/.system/imagegen/SKILL.md to understand how to use the image_gen tool.
Copy the output image to the current working directory and respond with the absolute path of the copied image file."
Example delegation parameters:
model: gpt-5.5cwd: the user's current working directory (absolute path)sandbox: danger-full-accessapproval-policy: neverprompt: e.g. "Generate a PNG image of a red origami fox sitting on a stack of books in a cozy library, soft warm lighting, shallow depth of field. Must use built-in image_gentool to generate image. Read the imagegen system skill at ~/.codex/skills/.system/imagegen/SKILL.md to understand how to use theimage_gen tool. Copy the output to the current working directory, and respond with ONLY the absolute path of the copied image file (no extra commentary)."
After receiving the response, surface the absolute path of the generated image to the user.
Known MCP Server Tools
- When
github MCP server tool (mcp__github, mcp__github__*) is requested, see mcp-github-usage.md for detailed usage instructions. Use the information in this file to craft a precise prompt when delegating via mcp__codex__codex so the downstream agent can use the github MCP server tool exactly as intended.
- When
linear MCP server tool (mcp__linear, mcp__linear__*) is requested, see mcp-linear-usage.md for detailed usage instructions. Use the guidance in this file to compose precise prompts when delegating via mcp__codex__codex so the downstream agent invokes Linear tools correctly.
- When
context7 MCP server tool is requested, see mcp-context7-usage.md for detailed usage instructions.
1---2name: codex-mcp3description: Use this `codex-mcp` skill to instruct another AI Agent to invoke a tool or execute a workflow on your behalf for the following scenario, 1.When you are requested to invoke a mcp tool that you don't have access (can use `ListMcpResourcesTool` to check) such as `context7`, `github`, `linear`, `jira`; 2.When you are requested to execute a complex workflow that require interacting with multiple mcp tools and bash CLI commands for example `github-project-create-items`, `github-project-list-items` workflows;4---5# codex-mcp67You MUST check whether `codex` CLI and MCP server are available in the current bash environment with this bash command: `codex mcp list`. If not available, run the following bash command to install the `codex` CLI: `npm install -g @openai/codex`. Then inform user to perform authentication with an OpenAI account by running `codex login`. Ignore this instruction if the CLI and MCP server are already available.89## Tools1011### mcp__codex__codex1213Run a Codex session. Accepts configuration parameters matching the Codex Config struct. Supported properties:1415| Property | Type | Description |16| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |17| **`prompt`** (required) | string | The initial user prompt to start the Codex conversation. |18| `approval-policy` | string | Approval policy for generated shell commands: `untrusted`, `on-failure`, `on-request`, `never`. |19| `base-instructions` | string | Overrides the default base instructions for the session. |20| `compact-prompt` | string | Prompt used when compacting the conversation. |21| `config` | object | Path to individual config settings toml file that override `$CODEX_HOME/config.toml` (see [codex-config-toml-structure.md](references/codex-config-toml-structure.md) to understand how to create this file). |22| `cwd` | string | Working directory for the session. Relative paths resolve from the server process root. |23| `developer-instructions`| string | Developer instructions that should be injected as a developer role message. |24| `model` | string | Optional override for the model name (e.g., `gpt-5.5`, `gpt-5.4-mini`, `gpt-5.4`, `gpt-5.4-nano`, `gpt-5.2`, `gpt-5.2-codex`) default is `gpt-5.4`. |25| `profile` | string | Name of the profile providing default options (defined in `config.toml`). |26| `sandbox` | string | Sandbox mode: `read-only`, `workspace-write`, or `danger-full-access`. |2728**Response:**2930| Property | Type | Description |31| ------------------------- | ------ | -------------------------------------------------------- |32| **`threadId`** (required) | string | Thread identifier (UUID) for the Codex session. |33| **`content`** (required) | string | The response content from the Codex session. |3435### mcp__codex__codex-reply3637Continue a Codex session by providing the conversation id and follow-up prompt. Supported properties:3839| Property | Type | Description |40| ------------------------------- | ------ | -------------------------------------------------------- |41| **`prompt`** (required) | string | Next user prompt to continue the Codex conversation. |42| **`threadId`** (required) | string | Identifier of the thread to continue. Must be a valid UUID (e.g., `019c08dc-ca4c-7a21-a0ce-b783c2cdec56`). |43| `conversationId` | string | **Deprecated.** Use `threadId` instead. |4445**Response:**4647| Property | Type | Description |48| ------------------------- | ------ | -------------------------------------------------------- |49| **`threadId`** (required) | string | Thread identifier (UUID) for the Codex session. |50| **`content`** (required) | string | The response content from the Codex session. |5152## Operational Requirements5354- Always route qualifying requests through `mcp__codex__codex` with `sandbox` set to `danger-full-access` (MUST) , `approval-policy` set to `never` (MUST) and `model` set to `gpt-5.4-mini` (SHOULD).55- When an unknown MCP tool name is requested, use `ListMcpResourcesTool` to confirm if it is available. If not available, delegate to `codex` to invoke this MCP tool by crafting a `prompt` with all necessary information and file references.56- When you need to run a command that would emit large stdout output but only a subset of that output is needed, MUST provide a precise `prompt` when delegating via `mcp__codex__codex` so the downstream agent knows which portion of the large output to collect or which external tool to execute.57- Prefer passing context via a local file when delegating: include a relative path prefixed with `@` inside the `prompt` (example prompt: "use mcp Github to submit all review feedback comments in this file @ghpr-code-review/pr_47_feat_e2e_tests_review_feedback.md Make sure to include correct line number for each comment").58- When `mcp__codex__codex` returns a result requiring your follow-up, continue the conversation with `mcp__codex__codex-reply`, reusing the `threadId` present in the previous response (must be a valid UUID).5960## Image Generation6162When the user requests to generate an image, delegate to `mcp__codex__codex` using `model` set to `gpt-5.5` (REQUIRED for image generation). The downstream Codex agent must:6364- Copy the generated image file to the current working directory (`cwd`).65- Return the **absolute path** of the copied image file in the response.6667When crafting the `prompt`, include explicit instructions such as:6869> "Generate an image of `{description}`.70> Must use built-in `image_gen` tool to generate image.71> Read the imagegen system skill at ~/.codex/skills/.system/imagegen/SKILL.md to understand how to use the `image_gen` tool.72> Copy the output image to the current working directory and respond with the absolute path of the copied image file."7374Example delegation parameters:7576- `model`: `gpt-5.5`77- `cwd`: the user's current working directory (absolute path)78- `sandbox`: `danger-full-access`79- `approval-policy`: `never`80- `prompt`: e.g. `"Generate a PNG image of a red origami fox sitting on a stack of books in a cozy library, soft warm lighting, shallow depth of field. Must use built-in `image_gen` tool to generate image. Read the imagegen system skill at ~/.codex/skills/.system/imagegen/SKILL.md to understand how to use the `image_gen` tool. Copy the output to the current working directory, and respond with ONLY the absolute path of the copied image file (no extra commentary)."`8182After receiving the response, surface the absolute path of the generated image to the user.8384## Known MCP Server Tools8586- When `github` MCP server tool (`mcp__github`, `mcp__github__*`) is requested, see [mcp-github-usage.md](references/mcp-github-usage.md) for detailed usage instructions. Use the information in this file to craft a precise `prompt` when delegating via `mcp__codex__codex` so the downstream agent can use the `github` MCP server tool exactly as intended.87- When `linear` MCP server tool (`mcp__linear`, `mcp__linear__*`) is requested, see [mcp-linear-usage.md](references/mcp-linear-usage.md) for detailed usage instructions. Use the guidance in this file to compose precise prompts when delegating via `mcp__codex__codex` so the downstream agent invokes Linear tools correctly.88- When `context7` MCP server tool is requested, see [mcp-context7-usage.md](references/mcp-context7-usage.md) for detailed usage instructions.
gosu-code