Skip to main content
Glama
codex-mcp-tool

codex-mcp-tool

image-gen

Generate or edit images via Codex with ChatGPT login and no API key; build structured prompts, then return saved file paths.

Instructions

Generate or edit images with Codex's built-in image_gen tool (ChatGPT login, no API key). Builds a structured prompt from use case, style, composition, exact text, reference roles and edit invariants, then returns the saved file paths. The image model and pixel size are chosen by Codex; aspect ratio and transparency are requested through the prompt.

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>"
    },
    "name": "image-gen"
  }
}

Input Schema

NameRequiredDescriptionDefault
textNoExact in-image text, rendered verbatim
avoidNoThings that must not appear
modelNoHost model that relays the call (not the image model). Known: gpt-6.1-sol, gpt-6-astra, gpt-6.1-terra, gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna. Omit to use the Codex default.
styleNoMedium and style, e.g. "35mm film photo", "flat vector"
aspectNoAspect ratio: square, landscape (3:2), portrait (2:3), wide (16:9), tall (9:16), or W:H. Requested via the prompt; exact pixel size is chosen by Codex.
promptYesWhat to create, or for edits, what to change. Be concrete about the subject.
enhanceNoLet the Codex host model enrich generic prompts with composition/lighting detail (never adds new subjects or text). false = pass the spec verbatim.
paletteNoColor palette
presetsNoGuidance blocks: photoreal, portrait, likeness, product, thumbnail, no-text, exact-text, brand-style
timeoutNoTimeout in ms. Default 10 min; each image takes roughly 30-90s.
useCaseNoTask category from the Codex imagegen taxonomy; sets the polish level
lightingNoLighting and mood
preserveNoEdit invariants, e.g. ["person and pose", "all text outside the sign"]
variantsNoNumber of images; each is a separate image_gen call
assetTypeNoWhere the image will be used, e.g. "landing page hero", "app store screenshot"
editImageNoImage to edit (absolute or relative to workingDir). Switches to edit mode.
materialsNoMaterials and textures
overwriteNoOverwrite an existing outputPath instead of writing a -v2 sibling
outputPathNoCopy results here (relative to workingDir). A path ending in / is a directory. Without it, images stay in $CODEX_HOME/generated_images.
referencesNoReference images with roles. Up to 5 images including editImage.
typographyNoFont style, size, color and placement for `text`
workingDirNoWorking directory for relative paths
compositionNoFraming, viewpoint, placement, negative space
reasoningEffortNoHost model reasoning. Default low: the host only relays the prepared spec.low
transparentBackgroundNoAsk for a transparent (alpha) background; check `hasAlpha` in the result

Output Schema

NameRequiredDescriptionDefault
specYes
errorNo
imagesYes
statusYes
threadIdNo
warningsYes
requestedYes
durationMsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.7.0

TDQS

A3.9/5.0
Behavior4/5

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

With annotations already declaring non-readOnly, openWorld and non-idempotent, the description adds real context annotations cannot: authentication is via ChatGPT login rather than API key, the host (not the caller) selects the image model and pixel size, and aspect ratio/transparency are hints routed through the prompt rather than hard parameters. It stops short of disclosing failure modes or what happens to existing files beyond the -v2 sibling rule documented in the schema.

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?

Three sentences, front-loaded with the verb and the resource, then the mechanics, then the constraints on what the caller actually controls. No restatement of the name or filler.

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?

Given 25 parameters, an output schema and full annotation coverage, the description covers the parts an agent must know before calling: auth, who picks the model/size, and that ratio/alpha are advisory. It does not address runtime cost or variant call multiplicity, but those are documented in the schema and output schema.

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 100%, so the baseline is 3, but the description earns an extra point by explaining that the many parameters are assembled into a structured prompt grouped by use case, style, composition, text, reference roles and edit invariants. It also flags the non-obvious semantics that aspect and transparency are prompt-level requests, not enforced settings.

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?

States a specific verb+resource pair ('Generate or edit images'), names the underlying mechanism (Codex's built-in image_gen, ChatGPT login, no API key), and says what it returns (saved file paths). Only the absence of explicit sibling differentiation keeps it from a 5, though no sibling in the list plausibly does image work.

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?

It implies the two modes (generation by default, edit mode triggered by editImage) and explains peripheral behaviors like enhance=false passing the spec verbatim, but never states when to prefer this tool over ask-codex or other siblings, nor any prerequisites or limits on use.

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