Codex ImageGen MCP

Overview Schema Source Related Servers Discussions Admin

Edit image

edit_image

Edit or transform images using a ChatGPT plan—no API key required. Provide 1-5 reference images, specify what to change, and get a new saved file.

Instructions

Edit or transform existing images, or create a new image guided by reference images, using the user's ChatGPT plan (no API key). Pass 1-5 images; refer to them in the prompt as Image 1, Image 2… (Image 1 is the primary edit target). State exactly what must change AND what must stay unchanged. Good for background replacement or removal, object removal/insertion, restyling, relighting, text localization, compositing and sketch-to-render. The input file is never modified; the result is saved as a new file.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`n`	No	Number of variants of this same prompt, 1-4 (default 1). Each variant is a separate request against the user's ChatGPT image quota. For several different assets make one call per asset instead.
`images`	Yes	1-5 input images: local file paths (absolute, ~/…, or relative to the workspace root), http(s) URLs, or data:image/…;base64 URLs. PNG, JPEG or WebP, up to 15 MB each.
`prompt`	Yes	Edit instructions, e.g. "Image 1: replace only the sky with a warm sunset; keep the building, people and framing unchanged."
`overwrite`	No	Replace an existing file at output_path (default false).
`background`	No	Background: "transparent" returns a PNG with a real alpha channel (cutouts, sprites, icons, stickers, logos); "opaque" asks for a filled background (a hint — also describe the backdrop in the prompt); "auto" (default) lets the service decide.	auto
`output_path`	No	Where to save: a .png/.jpg/.jpeg file path or a directory, absolute or relative to the workspace root. Omit to save in the server's image library (outside the project). Existing files are never replaced unless overwrite=true (a -2, -3… sibling is used instead); with n>1 a -1, -2… suffix is added.
`aspect_ratio`	No	Canvas shape: auto (default), 1:1, 4:5, 5:4, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9 or 9:21. The service chooses the exact pixel size from the prompt; this adds an explicit aspect-ratio line to it.	auto
`output_format`	No	File format: png (default) or jpeg (converted locally; cannot be transparent). Inferred from output_path's extension when given.
`include_preview`	No	Attach a downscaled preview so you can check the result visually (default true). Set false to save tokens.

Output Schema

TableJSON Schema

Name	Required	Description
`images`	Yes	Saved images (full resolution).
`prompt`	Yes	The exact prompt sent to the image service.
`failures`	Yes	Errors for variants that failed (partial success).
`warnings`	Yes
`elapsed_ms`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.2Sep 23, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description adds meaningful behavioral context: the operation uses the user's ChatGPT plan with no API key, the input file is never modified, and the result is saved as a new file. This complements destructiveHint=false and readOnlyHint=false without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficient: core capability first, then usage protocol, then example use cases, then a safety guarantee. Every sentence contributes, and no space is wasted on restating the title or repeating schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters and rich schema documentation, the description is largely complete: it covers the core workflow, prompt construction, non-modifying behavior, and output-file semantics. The only minor gap is explicit routing to sibling tools such as remove_background or generate_image in edge cases, but the strong schema compensates elsewhere.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, and the description adds extra value by specifying the prompt convention ('Image 1, Image 2…') and the Image 1 primary-target rule. It also clarifies that edits should explicitly preserve unchanged content, which is not fully captured by the schema's brief prompt example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource pair: 'Edit or transform existing images, or create a new image guided by reference images.' It enumerates concrete use cases and clearly distinguishes this reference-driven editing/creation tool from a plain text-to-image generator by requiring 1-5 reference images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit, actionable guidance: pass 1-5 images, refer to them as Image 1, Image 2..., keep Image 1 as the primary target, and state both what must change and what must stay unchanged. It does not explicitly name sibling alternatives like generate_image or remove_background, but the intended context is clear and practical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server