Teaching Codex to Paint: A Stateful Image-Editing Skill Built on Gemini's Interactions API and MCP

TL;DR: . There are two pieces to install:

• The skill goes in .agents/skills/nb2lite-image/ for one project, or ~/.agents/skills/nb2lite-image/ for every project.


• The MCP registration tells Codex how to start server.py and which environment-variable names to forward. The API key itself is never written into the Codex config.

Pick one path below. Each path installs both pieces unless noted otherwise.

Path A: The plugin marketplace (fewest keystrokes)

From a terminal, add the marketplace:

CODE Kopieren

codex plugin marketplace add xbill9/nb2lite-skill-codex

Then open Codex's Plugins Directory and install NB2Lite Image (nb2lite-image).

The plugin manifest points Codex at both the packaged skill and .mcp.json, so

the nb2lite-agent server is registered automatically.

The plugin intentionally carries no secret. Before launching Codex, expose your

key in the same shell:

CODE Kopieren

export GEMINI_API_KEY="your-key"

codex

Approve the server when Codex prompts, then run /mcp; it should list

nb2lite-agent and its four tools.

Path B: Clone and bootstrap (this repo)

CODE Kopieren

# 1. Get the code

git clone https://github.com/xbill9/nb2lite-skill-codex.git

cd nb2lite-skill-codex



# 2. One-command setup: installs deps, refreshes the repository skill,

#    and prompts for your API key (stored in ~/gemini.key)

./init.sh



# 3. Start or restart Codex from this checkout

codex

Inside Codex, approve the server and run /mcp. The checked-in

.codex/config.toml launches the authoritative root server.py; the repository

skill lives at .agents/skills/nb2lite-image/. init.sh is safe to rerun.

Path C: Project-scoped install

From a clone of the repo:

CODE Kopieren

make init TARGET=/path/to/your/project ARGS='--output-dir ./images'

This copies the skill into <project>/.agents/skills/nb2lite-image/ and writes

an idempotent nb2lite-agent block into <project>/.codex/config.toml. The

server path is absolute, while IMAGE_OUTPUT_DIR can be project-relative.

CODE Kopieren

cd /path/to/your/project

export GEMINI_API_KEY="your-key"

codex

Approve the server, then verify it with /mcp.

Path D: User-wide skill and MCP registration

To make the skill available to every Codex project:

CODE Kopieren

make init ARGS='--global'

This installs the skill under ~/.agents/skills/nb2lite-image/ and runs

codex mcp add to register nb2lite-agent in the user Codex configuration.

As with every other path, export GEMINI_API_KEY before starting Codex.

Path E: Manual Codex registration

If you already copied the skill and only need the MCP server, Codex can register

it directly:

CODE Kopieren

python3 -m pip install -r /absolute/path/to/nb2lite-image/mcp/requirements.txt

codex mcp add nb2lite-agent \

  --env GEMINI_MODEL_NAME=gemini-3.1-flash-lite-image \

  -- python3 /absolute/path/to/nb2lite-image/mcp/server.py

For a project-scoped setup, the equivalent .codex/config.toml block is:

CODE Kopieren

[mcp_servers.nb2lite-agent]

command = "python3"

args = ["/absolute/path/to/nb2lite-image/mcp/server.py"]

env_vars = ["GEMINI_API_KEY", "GOOGLE_API_KEY"]



[mcp_servers.nb2lite-agent.env]

GEMINI_MODEL_NAME = "gemini-3.1-flash-lite-image"

IMAGE_OUTPUT_DIR = "./images"

Notice the split: env_vars forwards secret values already present in the

shell; the [...env] table contains safe, non-secret defaults.

Path F: Docker (nothing on the host but Docker)

The server is published as . No manual compositing or retouching: Codex discovered the skill, called the MCP tools, read the saved paths, and produced the artifact used by the article.

Worth noticing:

• 
  The square concept became a real editorial asset. edit_local_image is the bridge from any file on disk into the stateful workflow.


• 
  The visual identity survived the format change. The graphite body, expressive eyes, and ultraviolet glow carry from the mascot study into the wide cover.


• 
  The next change would be stateful. The local edit returned an interaction ID, so another request—"make the MCP nodes brighter"—would use edit_image with the newest ID.

Dogfooding is the cheapest credibility there is: the tool's real output is

literally the first thing you saw when you opened this article. The cover also

tests more than generation—it exercises Codex skill discovery, MCP tool

registration, local-file editing, aspect-ratio adaptation, saving, and the

handoff to a real publishing workflow.

Links

• 
  Repo:
  


• 
  Interactions API reference:
  

This is a third-party community project, not affiliated with or endorsed by OpenAI or Google. Bring your own Gemini API key — and remember generations are billable, so draft on low and save high for the money shot.

Vollständiger Original-Bericht

Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

↗ Original-Artikel auf dev.to lesen