AI Head Swap with Claude MCP

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

Use Claude and Medux through MCP to replace the full head region between a source and target image. This guide keeps file roles and constraints in context, reviews the proposed call, and validates the returned result.

Final output: the source head is transferred while the target pose, clothing, and background remain intact.

Run AI Head Swap as a Claude MCP workflow

Keep the goal, source assets, and constraints together in the conversation. Ask Claude to restate the head donor image and target body image, with each role clearly assigned before proposing the Medux image head-swap tool. That context checkpoint makes the file roles and desired outcome easy to correct before any Medux call is approved.

Claude prompt pattern

Using the assets and requirements in this conversation, help me swap a full head in an image with Medux MCP.
Restate which input fulfills each role: the head donor image and target body image, with each role clearly assigned.
Propose the the Medux image head-swap tool call and summarize its arguments before asking for approval.
When it finishes, return the head-swapped image with a checklist confirming that the full intended head region is replaced while the target body and composition remain consistent.

Context checkpoint

Have Claude summarize the intended transformation, identify every source asset by role, and list the important constraints. Review that summary together with the proposed tool arguments; correct the conversation first if a file, order, time range, or setting is ambiguous.

Result verification

Keep the Medux task ID in the conversation while Claude checks progress. When processing ends, ask for the head-swapped image plus a concise validation checklist confirming 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.

How the workflow works

Claude handles orchestration. Medux handles image processing. MCP connects the two, keeping the task inside one agent workflow instead of requiring a separate dashboard or custom integration.

Describe the edit

Create upload URLs

Upload both images

Run and poll the task

Save the final image

Prerequisites

Source image

swap_head_src.jpg contains the head or identity to transfer.

Target image

swap_head_target.jpg provides the body, pose, clothing, and scene to preserve.

Claude workspace

Place both images in a project folder Claude can access.

Medux MCP connector

Enable the Medux connector before starting the task.

Image selection tip: use clear, well-lit faces with similar viewing angles. Cleaner inputs improve identity transfer and edge blending.

Step-by-step guide

Give Claude one precise instruction

Tell Claude which image supplies the new head, which image receives it, and that Medux must be called through MCP. The recording also asks Claude to upload the files with curl.

Swap the head in "swap_head_src.jpg" with the head in
"swap_head_target.jpg". Use Medux through MCP, upload the
files with curl, run the head-swap task, and save the result
in the current project folder.

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.

Reusable prompt

Replace the filenames and output path to reuse this workflow.

I have two images in this project:

- [SOURCE_IMAGE] contains the head to transfer.
- [TARGET_IMAGE] contains the body and scene to preserve.

Use the Medux MCP tools to create separate image upload URLs.
Upload both files with curl. Then run the Medux Head Swap task,
wait for completion, and save the final image as [OUTPUT_FILE].
Preserve the target pose, clothing, lighting, and background.

Pre-publish checklist

Before using the result on a public page, campaign, or product workflow, review the image carefully and confirm that you have permission to use both source images.

The transferred identity is recognizable.

The head scale matches the target body.

Hair and face edges are clean.

Skin tone and lighting are consistent.

The target scene remains unchanged.

Image-use permissions are confirmed.

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 Claude MCP?

Claude 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 keeps input roles and constraints in context, reviews the proposed call, and checks the returned result.

What does this Medux tutorial cover?

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

Run AI Head Swap as a Claude MCP workflow

Claude prompt pattern

Context checkpoint

Result verification

How the workflow works

Prerequisites

Step-by-step guide

Give Claude one precise instruction

Source, reference, and generated result

Reusable prompt

Pre-publish checklist

Explore related workflows

Related Medux tutorials

How do I run AI Head Swap with Claude MCP?

API reference for this workflow