Skip to main content
Start with ERD
Products -> ERDPricingDocsBlogSign in한국어Start with ERD

Codex

Connect OpenAI's Codex to AI-ERD via MCP.

Add the AI-ERD MCP server​

Register AI-ERD with the Codex CLI:

codex mcp add ai-erd --url https://ai-erd.com/mcp

Or add it to ~/.codex/config.toml yourself:

[mcp_servers.ai-erd]
url = "https://ai-erd.com/mcp"

Restart Codex. The first tool call against AI-ERD triggers the OAuth flow — sign in and approve.

Codex's MCP support changes; consult the Codex docs for the current configuration format if needed.

Roles per repository​

Codex keeps a single global MCP config, so ai-erd init does not touch it. Instead, init prints a profile to save as $CODEX_HOME/<role>.config.toml; start the session with codex -p <role> to run it in that role. See CLI → Set up a repository.

npx -y ai-erd@latest init                     # you, in a terminal: asks for the role and the project
npx -y ai-erd@latest init --role <role>       # an agent, with the role you chose

Try it​

Inside a Codex session:

List my AI-ERD ERD documents.
In ERD document <uuid>, add a posts table with columns: id (bigint pk auto), title (varchar 255 not null), body (text), author_id (bigint fk users.id), created_at (timestamp default now).

Codex will call the appropriate AI-ERD MCP tools and produce a snapshot tagged with your description.

Tips​

  • Be explicit about the ERD document - pass the UUID (or unambiguous title) so Codex doesn't have to guess.
  • Always include a description — every write tool requires it; a good description makes version history readable.
  • Check version history — every MCP write creates a snapshot you can restore.

Troubleshooting​

Codex doesn't show AI-ERD tools Re-check the config file location and TOML syntax. Codex must be restarted after editing config.

OAuth flow doesn't open Copy the URL from the terminal and open it manually.

Permission denied Confirm your AI-ERD account can edit the target document. MCP write tools respect the same role model as the web app - see Concepts -> Permissions.