Codex Image Generation MCP

Overview Schema Source Related Servers Discussions Admin

Generate Image

generate_image

Create or edit images from prompts, reference images, or masks, then save PNG, JPEG, or WebP files to a chosen project folder with preview paths.

Instructions

Generate/edit images and save originals in the current directory or requested folder.

Reuse Codex relay URL and credentials. Discover dialogue/image models independently; explicit responses_model/image_model values override automatic selection. When the user chooses this MCP, the host can reuse its installed system imagegen skill for prompt preparation and visual review while executing generation here. The server does not load skills itself; skill-specific built-in/CLI settings do not govern this tool. Supports PNG/JPEG/WebP, visual options, reference images and masks. Returns previews, absolute paths and edit IDs; successful images survive partial failures.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>",
      "cwd": "<cwd>"
    },
    "name": "generate_image"
  }
}

Input Schema

Name	Required	Description
`cwd`	Yes	Absolute CURRENT task working directory, supplied by Codex from context.
`mask`	No	Mask for the first image; local/data masks need alpha and must match comparable local input dimensions/format.
`size`	No	auto or WIDTHxHEIGHT. Model-specific limits are decided by upstream.
`action`	No	Choose automatically, generate, or edit supplied/previous images.
`prompt`	Yes	Describe what to draw or edit and important visual requirements.
`quality`	No	Optional quality; available levels depend on the upstream image model.
`filename`	No	Filename only, e.g. cover.webp. Infer format from extension; default is a unique name. Never overwrite existing files.
`background`	No	Transparent backgrounds require PNG or WebP.
`moderation`	No	Optional official moderation setting; upstream policy still applies.
`output_dir`	No	Directory relative to cwd or an explicitly requested absolute directory. Default: cwd itself.
`image_model`	No	Explicit tools[].model from the official image catalog. Omit for automatic selection; upstream_default omits the upstream field.
`input_images`	No	Reference images, each with exactly one path, image_url or file_id.
`model_policy`	No	Automatic model-selection preference. Default: configured policy, normally quality. Separate from image quality.
`current_model`	No	Exact dialogue-model API ID only when reliably known from the session. Otherwise omit; config fallback is explicit.
`output_format`	No	Infer from filename if omitted, otherwise default PNG. No SVG or animated output.
`input_fidelity`	No	Optional fidelity only if supported upstream; omit by default.
`partial_images`	No	0: final-only default. 1–3: streaming drafts and progress; host live display varies.
`include_preview`	No	Return bounded inline previews and original file paths.
`responses_model`	No	Explicit top-level dialogue model, overriding automatic provider-model selection; does not change the Codex session.
`safety_identifier`	No	Optional privacy-preserving end-user ID for multi-user deployments.
`output_compression`	No	JPEG/WebP only: strictly integer 0–100.
`previous_image_ids`	No	Prior image_generation_call IDs from the same provider.
`previous_response_id`	No	Prior response ID from the same provider; requires retained upstream state.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 3, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the bar is lower. The description still adds real context beyond them: originals are saved to cwd or a requested folder, previews plus absolute paths and edit IDs are returned, successful images survive partial failures, filenames never overwrite existing files, and explicit model values override automatic selection. It does not mention auth/rate limits, but the relay-credential reuse note hints at them.

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

Conciseness3/5

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

The core capability is front-loaded, but the paragraph is dense and mixes three separate concerns: generation, model/credential resolution, and host skill integration. Sentences like 'skill-specific built-in/CLI settings do not govern this tool' are noise for tool selection and dilute the actionable content.

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 23-parameter tool with no output schema, the description does the important work: it states where files land, what is returned (previews, absolute paths, edit IDs) and that partial failures still preserve successes. The only real gap is a fuller explanation of the edit workflow via previous_image_ids/previous_response_id and how state is retained upstream.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 23 parameters and the baseline is 3. The description adds a little beyond it, mainly the precedence rule that explicit responses_model/image_model override auto-selection, the supported formats PNG/JPEG/WebP, and that the server itself does not load skills or inherit skill-specific CLI settings. Those extras are marginal for a schema this well documented.

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

Purpose4/5

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

The description opens with a specific verb and resource: 'Generate/edit images and save originals in the current directory or requested folder.' That is enough for an agent to separate it from the sibling listing tools (list_models, list_image_models), which deal only with catalogs. It is clear but bloated by secondary sentences about skills and relay credentials.

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

Usage Guidelines3/5

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

Usage is only implied through the meaning of the tool and the 'action' parameter ('generate, edit supplied/previous images'). There is no explicit statement of when to call this versus asking list_image_models first, nor any prerequisite guidance. The sentence about the host reusing an installed imagegen skill describes integration plumbing, not when an agent should select this tool.

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

Deploy Server