AI generation API Codex: add a local MCP server with environment forwarding

Published 2026-10-23

Codex can use a local MCP server to access a custom generation workflow. The server translates a tool call into Genace REST requests and retains the credential outside the model’s arguments. You operate this wrapper yourself; it is not an official Genace Codex plugin. Begin by connecting the server and discovering its tools without creating any assets.

1. Prepare a reviewed wrapper

Use the implementation in the MCP tool tutorial, which exposes separate image submission and job inspection tools. Install its dependencies in an isolated Python environment. Record the absolute paths to the environment’s Python interpreter and the reviewed server file.

Set GENACE_API_KEY in the environment used to launch Codex. A GUI app opened before you changed a terminal environment may need a new launch environment. Do not put the real value in a chat prompt or a versioned configuration file just to make inheritance easier.

2. Add the MCP configuration

Merge this entry into your Codex config.toml, normally under your user Codex directory. Replace the paths with actual local paths. For a trusted project, Codex also supports project-scoped configuration; choose the scope that matches the intended access.

[mcp_servers.genace_local]
command = "/absolute/path/to/.venv/bin/python"
args = ["/absolute/path/to/genace_mcp.py"]
env_vars = ["GENACE_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 60

On Windows, forward slash paths such as C:/projects/assets/.venv/Scripts/python.exe avoid TOML backslash escaping. The env_vars setting allows the named variable to be forwarded; it is not the secret value itself. Preserve other MCP server tables when editing an existing file.

These fields follow OpenAI’s MCP configuration documentation. Check that page and your installed client version if a setting is rejected. A REST generation URL belongs inside the wrapper, not in a configuration field that expects an MCP server transport.

3. Verify discovery and tool scope

Restart or reconnect the client as needed and inspect the available tools. Verify that the paid tool accepts a prompt and the observation tool accepts a saved job ID. Neither tool should accept a secret, an arbitrary network destination, or an unrestricted upstream request body.

Ask Codex to explain the schema without invoking submission. Next, use mocked responses or a controlled existing job to verify status behavior. A pending job can have null outputs, and a failed generation can be returned by an otherwise successful HTTP request. Tool output needs the job state and error object for Codex to describe the result accurately.

4. Make one intentional asset request

When ready, request exactly one asset and specify that Codex should preserve the accepted ID. The submission response identifies it as job_id; later REST status responses use id. The wrapper normalizes this distinction, but your durable operation record should still retain the original accepted identifier.

Do not ask the assistant to keep invoking submission until an output appears. Rendering is asynchronous, so the correct follow-up action is observation of the same job. A local tool timeout or a closed Codex session does not cancel remote generation.

Common mistakes and verification

Avoid automatic POST retries after an uncertain response. This API route exposes no request idempotency contract, and a repeated tool invocation can create separate work. Do not return API keys in tool errors or print ordinary logs to stdout in a stdio server.

Verify the configuration parses, the interpreter imports its dependencies, and the server sees a nonempty credential without printing it. Confirm one explicit creation request produces one ID and that subsequent observations retain that ID. Finally, verify your own application policy can reject a paid call before it reaches the HTTP layer.

Continue with server-side keys and nonblocking agent workflows when you need persistent operation tracking.