How to Use OpenAI Codex Inside Claude Code with MCP

Claude Code is already capable of inspecting repositories, editing files, running commands, and coordinating complex engineering work. But there are times when you may want Claude to delegate a focused task to OpenAI Codex—for example:

Ask Codex to implement a change while Claude reviews it.
Use Codex for a second independent code review.
Let Codex clean up a technical review document.
Run a repeatable Codex skill from a Claude Code session.
Use Claude as the orchestrator and Codex as a specialist execution agent.

The cleanest way to build this workflow is through the Model Context Protocol, or MCP.

However, the phrase “install Codex inside Claude” can create the wrong mental model.

Codex is not inserted into the Claude model. Instead, Claude Code launches Codex as a separate local process and communicates with it through an MCP tool interface.

Claude orchestrates. Codex executes. Claude verifies.

Alt text: Claude Code connected to OpenAI Codex through an MCP stdio bridge.

Caption: Claude Code remains the orchestrator while Codex performs bounded delegated work.

What we are building

The final architecture looks like this:

You
 ↓
Claude Code
 ↓
Codex MCP tool
 ↓
codex mcp-server
 ↓
Codex session
 ↓
Repository files, commands and results
 ↓
Claude verifies the diff

OpenAI officially provides the codex mcp-server command for running Codex as an MCP server over standard input and output. The server exposes a codex tool for starting a session and a codex-reply tool for continuing an existing thread.

Claude Code supports local stdio MCP servers and provides the claude mcp add command for registering them.

This gives us a direct local connection:

Claude Code ──stdio MCP──> Codex CLI

There is no custom Python service, remote server or API wrapper required for the basic setup.

Prerequisites

You need:

Claude Code installed and working.
Node.js and npm available in your terminal.
OpenAI Codex CLI installed.
A valid Codex authentication method.
A local Git repository for testing.

Create a Git checkpoint before allowing either agent to make substantial changes. It is much easier to review or undo an agent task when the working tree begins in a known state.

Step 1: Install the Codex CLI

Open PowerShell, Windows Terminal, Terminal, or your preferred shell.

Install Codex globally:

npm install -g @openai/codex

OpenAI distributes current Codex CLI releases through the @openai/codex npm package.

Confirm that the command is available:

codex --version

Then launch Codex once:

codex

During the first launch, complete the available sign-in flow. The official quickstart instructs users to run codex from a project directory and authenticate during the initial session.

After authentication, exit Codex and return to the normal terminal.

Step 2: Register Codex in Claude Code

For a Codex connection available across all your Claude Code projects, run:

claude mcp add --transport stdio --scope user codex -- codex mcp-server

The parts of this command mean:

claude mcp add

--transport stdio

Start it as a local process communicating through standard input and output.

--scope user

Make the server available to your user account across projects.

codex

The name Claude Code will use for the MCP server.

-- codex mcp-server

The command Claude Code starts when it needs the server.

Claude Code requires the double dash before the executable because it separates Claude’s configuration flags from the command and arguments passed to the MCP server.

Project-only installation

To commit the configuration with one repository, use project scope:

claude mcp add --transport stdio --scope project codex -- codex mcp-server

Project-scoped MCP servers are stored in a .mcp.json file at the project root. Claude Code requires approval before using MCP servers loaded from a repository, especially when the workspace has not yet been trusted.

Which scope should you choose?

Use user scope when Codex is a personal development tool you want available everywhere.

Use project scope when the whole team should receive the same Codex MCP configuration after cloning the repository.

Avoid installing the same server under multiple scopes unless you intentionally need separate configurations.

Step 3: Verify the connection

List your configured MCP servers:

claude mcp list

You should see a Codex entry with a connected status.

You can inspect it directly:

claude mcp get codex

Now launch Claude Code:

claude

Inside the Claude Code session, open the MCP panel:

/mcp

Claude Code documents /mcp, claude mcp list, claude mcp get, and claude mcp remove as the standard ways to inspect and manage configured servers.

Step 4: Run a controlled Codex test

Do not begin with a broad instruction such as:

Use Codex to improve this project.

That leaves too many decisions undefined.

Use a bounded test instead:

Use the Codex MCP tool to perform this task.

Claude must only orchestrate and verify. Codex must perform the work.

Codex configuration:
- cwd: the current repository
- sandbox: workspace-write
- approval-policy: never

Task:
Inspect README.md and create CODEX_CONNECTION_TEST.md containing:
1. The project name
2. A three-sentence project summary
3. The main technologies detected from repository files

Do not modify any other file.

After Codex finishes, verify that:
- Only CODEX_CONNECTION_TEST.md was created
- The contents are supported by repository evidence
- No unrelated files changed

The Codex MCP codex tool accepts an explicit prompt, working directory, sandbox mode, approval policy, model and configuration overrides. Supported sandbox modes include read-only, workspace-write, and danger-full-access.

For ordinary repository editing, workspace-write is a sensible default.

It allows Codex to work inside the repository without automatically granting unrestricted access to the rest of the machine.

What happens under the hood

Alt text: Six-step sequence showing a request moving from the user to Claude, MCP, Codex, the workspace and back to Claude for verification.

Caption: A delegated task is a controlled handoff between two separate agent sessions.

When you submit the test prompt, the following sequence occurs.

1. Claude interprets the request

Claude reads your current conversation, Claude instructions, project files and any Claude skills it has loaded.

2. Claude creates an MCP tool call

Claude prepares a structured call containing information such as:

The Codex prompt
Repository working directory
Sandbox mode
Approval policy
Optional developer instructions
Optional model or configuration overrides

3. Claude Code launches the Codex server

Claude Code starts:

codex mcp-server

The MCP communication travels through stdin and stdout.

4. Codex starts a separate session

Codex receives the prompt and begins its own agent session.

This is the most important architectural point:

Codex does not become part of Claude’s context window.

The guaranteed Codex inputs are the fields supplied through the MCP call and the files Codex can access from its assigned environment.

This conclusion follows from the explicit MCP tool contract: the calling client supplies the prompt, cwd, sandbox, approval policy and optional instructions when starting a Codex session.

5. Codex performs the work

Depending on its permissions and instructions, Codex may:

Inspect repository files
Edit files
Run commands
Execute tests
Produce an analysis
Return a result with a thread ID

6. Claude verifies the result

Claude receives the tool output and can:

Inspect the modified file
Run git diff
Check tests
Compare the result with the original requirements
Ask Codex to correct a specific issue using codex-reply

This division creates a useful separation of responsibilities:

Claude: planning, delegation and acceptance
Codex: focused execution
Git/tests: objective evidence

The skill boundary most people miss

Claude Code and Codex both support reusable skills, but a skill loaded by Claude is not automatically delivered to Codex.

Alt text: Diagram showing separate Claude Code and Codex skill locations divided by an MCP context boundary.

Caption: Each agent loads skills from its own environment. Only explicitly supplied context crosses the MCP boundary.

Claude Code skills commonly live under:

.claude/skills/<skill-name>/SKILL.md

Claude can load one automatically or invoke it with a slash command such as:

/session-handoff

Anthropic documents Claude Code skills as SKILL.md workflows that can be invoked directly or loaded when relevant.

Codex personal skills live under:

$HOME/.agents/skills/<skill-name>/SKILL.md

On Windows, that is typically:

%USERPROFILE%\.agents\skills\<skill-name>\SKILL.md

Repository-level Codex skills live under:

<repository>\.agents\skills\<skill-name>\SKILL.md

OpenAI documents personal skills under $HOME/.agents/skills and shared repository skills under .agents/skills.

Codex can select a skill implicitly from its description, or you can invoke it explicitly by mentioning the skill with $skill-name.

Example: Give Codex its own handoff skill

Suppose Claude already has this skill:

.claude/skills/session-handoff/SKILL.md

You can create a Codex-compatible counterpart:

.agents/skills/session-handoff/SKILL.md

A minimal version could look like this:

---
name: session-handoff
description: Create a comprehensive project or agent-session handoff document.
---

# Session Handoff

1. Inspect the repository and supplied session evidence.
2. Record the project purpose, architecture and important files.
3. Document completed work, current state and unresolved issues.
4. Clearly separate verified facts from assumptions.
5. Include information about the outer agent session only when it was
   explicitly supplied in the prompt or referenced files.
6. Write the result to docs/handoffs/ unless another path is specified.
7. Do not modify unrelated files.
8. Report the output path and any missing context.

Then instruct Claude to invoke the Codex skill explicitly:

Use the Codex MCP tool.

Claude must orchestrate and verify only. Codex must author the document.

Codex configuration:
- cwd: the current repository
- sandbox: workspace-write
- approval-policy: never

Send Codex this prompt:

$session-handoff

Create a handoff document for this project.

Treat the following as authoritative evidence from the outer Claude Code
session:

- Decisions: [insert decisions]
- Modified files: [insert files]
- Completed verification: [insert tests or checks]
- Remaining tasks: [insert tasks]
- Unresolved questions: [insert questions]

Write the final document to:
docs/handoffs/HANDOFF_CURRENT_SESSION.md

Do not modify any other file.

The $session-handoff reference removes uncertainty about whether Codex should load that skill.

Claude still has an essential responsibility: it must supply any outer-session information that Codex cannot independently reconstruct from the repository.

That includes information such as:

Conversation-only decisions
Claude’s private task state
Background process identifiers
Temporary plans
Uncommitted reasoning
Information that was never written to disk

Your working examples correctly distinguish this outer-session context from the files and prompts available to the Codex process.

Practical example: Remove fixed issues from a review document

Consider a review file:

REVIEW_2026-07-02_shared-core-modules.md

It contains open findings along with findings explicitly marked as fixed.

The goal is to remove complete fixed issue blocks without asking Codex to inspect the source code or independently decide whether an issue has been resolved.

Paste this into Claude Code:

Use the Codex MCP tool to perform the following task.
Claude must not edit the document itself.

Codex configuration:
- cwd: the current repository
- sandbox: workspace-write
- approval-policy: never

Edit REVIEW_2026-07-02_shared-core-modules.md in place.
Do not modify any other files.

Remove each issue block that is explicitly marked **FIXED** — the whole block
including its heading, status, verification details, and any bullets or
paragraphs belonging only to it.

Do not remove only the FIXED line.

Keep every issue that is not explicitly marked FIXED, including partially
fixed, open, blocked, unresolved or ambiguous issues. Preserve its wording
except for necessary numbering or formatting updates.

Judge status only from what this document records.

Do not inspect source code.
Do not independently decide whether another issue has been fixed.
Do not invent or upgrade issue statuses.

After removing the fixed blocks:

1. Renumber the remaining issues sequentially.
2. Update affected summary counts.
3. Update the table of contents, indexes and internal cross-references.
4. Retain and report any issue whose status is ambiguous.

Report:
- Number of fixed issue blocks removed
- Number of issues remaining
- Ambiguous items retained
- Confirmation that no other files were modified

After Codex finishes, Claude must inspect a diff limited to this document and
verify that complete fixed issue blocks were removed while unresolved issues
were preserved.

This prompt is strong because it defines five boundaries:

Who performs the edit: Codex.
What file may change: one review document.
What counts as removable: only an explicit fixed marker.
What evidence Codex may use: the document itself.
How the result is accepted: Claude verifies the diff.

The original handoff and review-cleanup discussion that informed these examples is captured in the supplied working context.

A reusable Claude-to-Codex delegation template

Use this template for most delegated editing tasks:

Use the Codex MCP tool.

Responsibility:
- Claude must orchestrate and verify.
- Codex must perform the requested work.
- Claude must not silently replace Codex as the author.

Codex configuration:
- cwd: [repository path or current repository]
- sandbox: [read-only or workspace-write]
- approval-policy: never

Allowed files:
- [file or directory list]

Task:
[Exact result Codex must produce]

Constraints:
- Do not modify unrelated files.
- Do not expand the task without permission.
- Do not claim success without evidence.
- Preserve existing behavior unless explicitly instructed otherwise.
- Flag ambiguous requirements instead of guessing.

Verification Codex should perform:
- [test, command, parser, validation or file check]

Report:
- Files changed
- Commands run
- Verification results
- Assumptions
- Remaining uncertainty

After Codex completes:
Claude must inspect the diff and verify the result against every requirement.

For analysis-only work, change the sandbox to:

sandbox: read-only

For an edit, use:

sandbox: workspace-write

Avoid danger-full-access unless the task genuinely requires operations outside the workspace and you have reviewed the risk.

Common mistakes

Mistake 1: “Use Codex” without requiring a tool call

A natural-language request does not create a hard delegation contract.

Better:

Use the Codex MCP tool. Codex must author the result. Claude must only
orchestrate and verify.

Mistake 2: Assuming Claude skills automatically transfer

Claude may have loaded an excellent handoff or review skill, but Codex does not automatically inherit that loaded skill body.

Either:

Pass the complete procedure in the Codex prompt, or
Install a Codex-compatible skill and invoke it with $skill-name.

Mistake 3: Omitting the working directory

Always supply the correct cwd.

Otherwise, Codex may start without the repository context you expected or operate against the wrong project directory.

Mistake 4: Allowing the agent to change any file

Name the allowed files or directories.

For narrow document-cleanup work, explicitly say:

Do not modify any other file.

Mistake 5: Asking Codex to determine facts it does not need

When cleaning a review document, do not ask Codex to inspect the implementation unless source verification is part of the task.

Use the document’s recorded status as the authority when that is the intended workflow.

Mistake 6: Skipping Claude’s verification step

Delegation is not complete when Codex says “done.”

Claude should inspect:

git status --short
git diff -- path/to/allowed-file

It should also run any required tests, parsers, schema validators or formatting checks.

Mistake 7: Duplicating the same skill globally and locally

Codex can discover personal and repository skills.

Installing identical copies in both locations can make maintenance confusing. Prefer:

Global for personal reusable workflows
Repository level for project or team-specific workflows

Troubleshooting

`codex` is not recognized

Confirm npm’s global binary directory is on your PATH.

Then reinstall:

npm install -g @openai/codex

Open a new terminal and run:

codex --version

Codex MCP shows as disconnected

Test the server directly:

codex mcp-server

It may appear to wait silently because an MCP stdio server expects an MCP client to communicate over stdin.

Stop it with Ctrl+C, then inspect Claude’s configuration:

claude mcp get codex

Authentication fails

Run Codex interactively:

codex

Complete authentication before asking Claude Code to launch it as a background MCP process.

Project MCP server is pending approval

Launch Claude Code interactively inside the repository, trust the workspace and review the MCP server request.

Project-scoped .mcp.json servers may remain pending until the workspace approval flow is completed.

Codex edits the wrong project

Supply the cwd parameter explicitly in the delegation prompt and ask Claude to report the directory it sent.

Claude writes the result instead of Codex

Strengthen the responsibility contract:

Codex must author and save the final result.
Claude must not draft or rewrite it.
Claude may only inspect, test and report specific verification failures.

The reliable operating model

The most dependable pattern is not “two agents chatting freely.”

It is a controlled engineering pipeline:

REQUEST
   ↓
CLAUDE PLANS
   ↓
CLAUDE DEFINES THE CONTRACT
   ↓
CODEX EXECUTES IN A BOUNDED WORKSPACE
   ↓
TOOLS AND TESTS PRODUCE EVIDENCE
   ↓
CLAUDE ACCEPTS OR REJECTS THE RESULT

This pattern gives each component a precise role:

Component	Responsibility
You	Define the desired outcome
Claude Code	Plan, supply context and orchestrate
MCP	Carry the structured tool call
Codex	Execute the delegated task
Git and tests	Produce objective evidence
Claude Code	Verify and report

The important idea is not merely that Claude can call Codex.

The important idea is that the handoff can be made explicit, bounded, reviewable and repeatable.

Once that contract is in place, Codex becomes a useful specialist inside a broader Claude Code workflow—without pretending that the two agents automatically share context, skills or state.

Quick setup reference

# Install Codex
npm install -g @openai/codex

# Authenticate
codex

# Add Codex as a user-scoped Claude Code MCP server
claude mcp add --transport stdio --scope user codex -- codex mcp-server

# Verify
claude mcp list
claude mcp get codex

# Start Claude Code
claude

# Inside Claude Code
/mcp

Then delegate with:

Use the Codex MCP tool.

Claude must orchestrate and verify.
Codex must perform the task.

Use:
- cwd: current repository
- sandbox: workspace-write
- approval-policy: never

Task:
[Your bounded task]

Do not modify unrelated files.
Report files changed and verification performed.

That is the complete foundation for using OpenAI Codex from inside a Claude Code workflow.

Run OpenAI Codex Inside Claude Code via MCP