Codex CLI · ~/.codex/config.toml · TOML

Image generation in Codex: MCP server setup

Add an [mcp_servers.imagemcp] table to ~/.codex/config.toml with url and http_headers, or run codex mcp add — Codex is the one client here configured in TOML rather than JSON. Codex is comfortable rewriting a component and leaving the image import pointing at a file that was never generated. Giving it the image tools closes that gap inside the same run.

By the imagemcpserver.com teamPublished Codex docs checked September 2026
Get a free API key Generic MCP docs

Add the server

Where the config lives
~/.codex/config.toml (user) · .codex/config.toml (trusted projects)
The key it nests under
[mcp_servers.<name>]
  1. 1

    Create an API key. Create a key in the imagemcpserver dashboard.

  2. 2

    Open config.toml. Edit ~/.codex/config.toml, or use codex mcp add to have Codex write the entry.

  3. 3

    Add the mcp_servers table. Set url to the endpoint and pass the key via http_headers or env_http_headers.

  4. 4

    Verify with /mcp. Start a Codex session and run /mcp to confirm the server connected and see its tools.

codex · recommendeduse this
# ~/.codex/config.toml
[mcp_servers.imagemcp]
url = "https://mcp.imagemcpserver.com/mcp"
http_headers = { "x-api-key" = "sk-img-gen-…" }
startup_timeout_sec = 30
Keep the key in the environment
# env_http_headers maps a header name to an env var name,
# so the key never lands in the file.
[mcp_servers.imagemcp]
url = "https://mcp.imagemcpserver.com/mcp"
env_http_headers = { "x-api-key" = "IMAGEMCP_API_KEY" }

# Or add it from the shell instead of editing TOML:
#   codex mcp add imagemcp --url https://mcp.imagemcpserver.com/mcp

TOML, and three ways to send the key

Codex is the odd one out: every other client on this list takes JSON or YAML, Codex takes TOML. It also gives you three header mechanisms — http_headers for a static value, env_http_headers to read one from the environment, and bearer_token_env_var if you would rather send an Authorization bearer token. This server accepts all three, so pick on taste rather than necessity.

The endpoint and the key are identical in every client. The wrapper around them is not, and that wrapper is where almost every “correct” config that does nothing goes wrong. Checked September 2026 against Codex’s own documentation — see the sources below.

Three ways to send the key

The server resolves your API key from any of these, checked in this order. That matters when a client only gives you a URL field and no way to set a header — you are not stuck, and you do not need a bridge process.

Query parameter

?apikey=sk-img-gen-…

Checked first. The fallback for a client whose config is a bare URL field.

x-api-key header

x-api-key: sk-img-gen-…

The documented default, and what every client below uses unless noted.

Authorization header

Authorization: Bearer sk-img-gen-…

Accepted as a bearer token, which is what a client with only a token field will send.

A key in a query string ends up in shell history, process listings and any log the client keeps, so prefer a header where the client allows one. Where it does not, treat the whole URL as the secret and rotate it as freely as you would a password.

What each tool costs

Wherever Codex lets you approve tools individually, the useful line to draw is not between image tools and other tools — it is between calls with a fixed price and calls that route to a model.

get_user_infolist_models

free

Safe to auto-approve wherever the client supports it. These are how the agent finds out what it can afford before it spends anything.

compress_imageconvert_format

1 credit

Deterministic and cheap. Auto-approving these makes an optimisation pass over a whole folder painless.

remove_backgroundtext_to_svgupscale_image

5–15 credits

Fixed prices, no model routing. Auto-approve once you trust the workflow.

generate_imageedit_imagegenerate_transparent_imagemulticall

model-priced

These route to an image model and are the ones that can run up a bill in a loop. Keep approval on.

Codex questions

Where is the Codex MCP config file?

MCP servers live in the same file as the rest of your Codex configuration: ~/.codex/config.toml by default. You can also scope a server to one project with .codex/config.toml, which Codex only reads for trusted projects.

Can Codex send a custom header rather than a bearer token?

Yes. http_headers takes a map of header names to static values, and env_http_headers takes a map of header names to environment variable names. bearer_token_env_var exists too if you prefer an Authorization bearer token — this server accepts that form as well.

How do I add an MCP server to Codex from the command line?

codex mcp add <name> --url <endpoint>. It edits config.toml for you, which avoids a hand-written TOML table with a typo in it.

Why do I not see the image tools in my session?

Run /mcp first — it reports each configured server and whether it actually connected. If the server is listed but has no tools, the key was rejected; if it is not listed at all, Codex never read the table, which usually means it went into the wrong file.

Does this work in the Codex IDE extension and the ChatGPT app too?

The CLI is what this page covers. The Codex extension reads the same config.toml, so a server added here shows up there. For the ChatGPT connector surface, see the ChatGPT integration guide instead.

Sources & references

Zed →Goose →All clients