Happy slice of mcp pizzaMCP.pizza
codex-image-context-runtime

codex-image-context-runtime

MCP.Pizza Chef: shixinnt

This server plugin for Codex lets you generate and inspect images as manageable jobs that keep your workspace responsive. It works inside Codex desktop or CLI apps with plugin support, handling images by returning text references and job IDs instead of raw pixels. You can use it offline with a mock provider or connect it to OpenAI for real image generation. Setup requires some developer steps like cloning and configuring environment variables.

Images/Design
Other

Use This MCP server To

Generate storyboard frames for a project without slowing Codex Create multiple visual variations of images efficiently Inspect images for composition and text defects with text summaries Organize and manage image-heavy research or news content Run repeated visual quality checks on generated images Keep image generation tasks resumable and context-bounded in Codex

README

简体中文

Image Context Runtime logo

Image Context Runtime for Codex

Keep image-heavy Codex workflows responsive, resumable, and context-bounded.

A conceptual workstation comparison of image-heavy Codex tasks with and without Image Context Runtime

Fictional concept interface—not an actual Codex UI or a measured context, token, speed, or latency benchmark.

Image Context Runtime for Codex is an experimental open-source Codex plugin backed by a durable local MCP runtime. It runs image generation and inspection as persisted jobs, keeps provider-returned media bytes behind the public MCP boundary, and returns only bounded text results, hashes, relative references, and Job IDs.

Use it when Codex is:

  • creating short-drama character sheets, location concepts, or storyboards;
  • producing image assets for websites and slide decks;
  • organizing image-heavy news, books, screenshots, or research;
  • generating many visual variations or running repeated visual QA.

Important: This project reduces one source of context pressure. It does not claim that Codex can never slow down, that images use zero tokens, or that explicitly opening an image adds no visual context.

The plugin does not patch or intercept Codex's built-in image features or other image tools. The bounded boundary applies only when Codex uses this plugin's MCP tools and follows its bundled skill.

What it is

User-facing shape: a Codex plugin.

Execution shape: a bundled local MCP server plus a durable image-job runtime.

Codex skill
    |
    v
bounded MCP tools
    |
    v
durable local jobs ----> optional OpenAI API
    |
    +----> configured-workspace image artifacts
    |
    +----> bounded text handoffs, hashes, refs, and Job IDs

The plugin is the installable workflow. MCP is the tool boundary. The Runtime owns Job state, controls media transfer, and writes generated artifacts only to configured workspace-relative paths.

Public v0.2 scope

  • Text-to-image jobs.
  • Image inspection jobs.
  • Durable status and text handoffs.
  • Idempotent submission.
  • Restart reconciliation and explicit recovery.
  • Offline deterministic mock provider.
  • Optional OpenAI Image API and Responses API provider.
  • Strict public-result budgets with no MCP image, audio, or resource blocks.
  • One authenticated loopback broker shared safely by multiple Codex task bridges.
  • Cursor-based Job history and explicit privacy-minimizing terminal-record compaction.

Video generation is intentionally out of scope for v0.2.

Requirements

  • Node.js 22 or later.
  • Codex desktop app or Codex CLI with plugin support.
  • No API key for the default mock provider.
  • OPENAI_API_KEY only when the OpenAI provider is explicitly enabled.

codex-image-context-runtime FAQ

Can I use this to generate images within Codex?
Yes — it lets Codex create images as jobs with controlled context and returns references instead of raw image data.
Can I use this to inspect images and get text-based feedback?
Yes — it provides bounded text inspection results for images without sending the full image data back.
Which apps support this server?
It works with the Codex desktop app and Codex CLI that support plugins, including the Cursor client.
Do I need an API key to use this?
No API key is needed for the default offline mock provider. An OpenAI API key is required only if you enable the OpenAI provider.
How hard is it to set up?
Setup requires developer skills, including cloning the repo, running commands, and configuring environment variables.
Can I switch between offline and OpenAI providers?
Yes — you can configure the runtime to use either the offline mock or OpenAI provider by changing settings and environment variables.