AI Head Swap with Codex MCP

How to swap a full head in an image with Codex MCP and Medux

Use Codex and Medux through MCP to replace the full head region between a source and target image. This guide covers input preparation, the approval gate, task monitoring, and a concrete output check.

Watch the complete workflow: AI image head swap with Codex, MCP, and Medux.Watch on YouTube ↗

Run AI Head Swap as a Codex MCP task

Use the active workspace as the source of truth. Ask Codex to identify the head donor image and target body image, with each role clearly assigned, select the Medux image head-swap tool, and keep the Medux task ID and returned output with the rest of the project. Naming the input roles and the expected result prevents an agent from guessing which file should be used where.

Codex prompt pattern

In this workspace, use the Medux image head-swap tool through Medux MCP to swap a full head in an image.
First inspect and identify the head donor image and target body image, with each role clearly assigned.
Show me the exact tool arguments before execution.
After the task completes, return the head-swapped image and verify that the full intended head region is replaced while the target body and composition remain consistent.

Approval gate

Before approving the call, compare the selected tool, file or asset IDs, ordering, timing, and output settings with the request. If a local filename was mapped to an uploaded Medux file ID, keep that mapping visible so it can be audited later.

Result verification

Let Codex monitor an asynchronous task until it reaches a terminal state, then save or report the head-swapped image. The final check is explicit: confirm that the full intended head region is replaced while the target body and composition remain consistent.

Capability boundary: This tutorial targets image head swap: it replaces the broader head region using a donor and target image. Face swap is documented separately because it transfers facial identity while preserving more of the target head.

Before you start

The demo uses two local JPG files. One image provides the replacement head, and the other image provides the base body or scene.

swap_head_src.jpgThe replacement head image. In the video, Codex treats this as the head donor.

swap_head_target.jpgThe base image. Medux keeps this image as the body and scene recipient.

Keep filenames simple and place both images in the same Codex project workspace. This makes the MCP flow easier to repeat and review.

Step-by-step workflow

Ask Codex to run the Medux head-swap tool

Use a direct prompt. Codex should know which image is the head donor and which image is the target body.

Swap the head in "swap_head_src.jpg" with the head in "swap_head_target.jpg". Use medux. head swap!

Prompt asking Codex to swap a head with Medux — Codex receives the head-swap instruction and begins planning the Medux workflow.

Let Codex locate files and select the correct Medux endpoint

Codex lists the local files, finds the Medux head-swap tool, and avoids using a generic face-swap endpoint. This matters because the task is specifically a head replacement, not just a facial blend.

Codex finds local files and prepares upload slots — Codex confirms the two JPGs and prepares Medux upload slots for each file.

Submit the head-swap task

After both images are uploaded, Codex submits the Medux task. In this demo, swap_head_src.jpg is passed as the replacement head and swap_head_target.jpg is passed as the base image.

The important control point is role assignment: donor head first, target body second. This keeps the output aligned with the user request.

Codex submits a Medux head-swap task and polls the status — Codex sends the job to Medux and waits instead of returning only a task ID.

Poll until Medux returns the output

Codex keeps checking the task status as it moves from QUEUED to PROCESSING. Once the render is complete, it returns an output file such as head_swap_output.png plus the task ID for traceability.

Medux head swap success message in Codex — The final result is returned as an image output that can be opened, downloaded, or used in the next workflow.

Head swap example

Source, reference, and generated result

Compare the three images below to see how the source image, target reference, and final Medux output relate to one another.

Source image for the Medux head swap example — Original image used as the base input.

Target reference for the Medux head swap example — Reference image that provides the head and styling direction.

Generated result for the Medux head swap example — Final head-swap image generated through Medux.

Publish-ready summary

Medux turns image editing into an agent-friendly workflow. Instead of manually uploading assets, choosing endpoints, and polling job status, Codex can call Medux through MCP and operate the full head-swap pipeline from one prompt.

Clear input roles
Use one image as the replacement head and one as the base image.

Agent-operated flow
Codex selects the Medux tool, uploads files, and starts the job.

Reviewable output
The final PNG is returned with a task ID for easy checking.

Explore related workflows

Continue with a nearby Medux workflow or compare how the same task works across Claude MCP and Codex MCP.

How do I run AI Head Swap with Codex MCP?

Codex can use the Medux image head-swap tool through Medux MCP to replace the full head region between a source and target image. The workflow identifies the exact inputs, reviews the tool arguments, monitors processing, and verifies the returned result.

What does this Medux tutorial cover?

Related topics: AI Head Swap · AI Head Swap with Codex MCP · Medux MCP tutorial

Run AI Head Swap as a Codex MCP task

Codex prompt pattern

Approval gate

Result verification

Before you start

Step-by-step workflow

Ask Codex to run the Medux head-swap tool

Let Codex locate files and select the correct Medux endpoint

Submit the head-swap task

Poll until Medux returns the output

Source, reference, and generated result

Publish-ready summary

Explore related workflows

Related Medux tutorials

How do I run AI Head Swap with Codex MCP?

API reference for this workflow