Codex

Deploy from Codex, with your own tool allow-list

Aria AI can run on your Codex subscription, and Codex can connect on its own over MCP: a table in config.toml, a key from your environment, and an AGENTS.md it already reads.

Get your serverConnection reference

Checked against the product on

Two ways to work

Aria AI first. MCP when you want it.

Aria AI is built into Aria. Codex over MCP is for working outside it. The same rules apply to both.

1

Aria AI

The AI built into Aria. It writes aria.yaml, sets things up, reads logs and fixes things, inside the Mac app and the web dashboard.

On the Mac, your subscription

Aria finds the coding tool on your Mac, shows who it is signed in as and asks “Is this the one?”. One click and it is connected. The turns run on your own Mac. Choose Codex and Aria AI uses the plan you already pay for.

  • Claude Code
  • Codex
  • Gemini CLI
  • Cursor

In the browser, an API key

Paste a key in AI & MCP and Aria AI works in the web dashboard, wherever you are signed in.

  • Anthropic
  • OpenAI
  • Gemini
  • OpenRouter
Connect Aria AI
2

MCP

For a coding agent working outside Aria. It calls Aria’s tools with a key that reaches one app. Run aria init or aria mcp add.

  • Claude Code
  • Cursor
  • Codex
  • Gemini CLI
  • Antigravity
Connect a coding agent

MCP

How do you connect Codex?

The command writes the file for you. By hand, export the key and add one table.

What the command does

aria mcp add --agent codex asks you to approve a new key in Aria, then adds the server to ~/.codex/config.toml. With --app wsp_YOURAPP it also installs the Aria skill for Codex. It writes the key into the file, so it sets the file to be readable only by you.

By hand, export ARIA_MCP_KEY in the shell you start Codex from, and add the table. Codex reads the variable when it starts. Check with codex mcp list.

Terminal
aria loginaria mcp add --agent codex
~/.codex/config.toml
[mcp_servers.aria-myapp]url = "https://api.getaria.cloud/mcp/w/wsp_YOURAPP"bearer_token_env_var = "ARIA_MCP_KEY"

How do you narrow what Codex can call?

Codex lets you allow or deny single tools of a server and choose how it asks. Aria’s levels run underneath.

OpenAI’s documentation, read on 31 October 2026, lists these keys for a server table: enabled_tools as an allow list, disabled_tools as a deny list applied after it, and default_tools_approval_mode with the values auto, prompt, writes and approve. A single tool can have its own approval_mode.

This example asks before every Aria tool and removes db_migrate, the one that changes data, so Codex never proposes it. Check the keys against your Codex version. The tool names and levels are on the safety model.

~/.codex/config.toml
[mcp_servers.aria-myapp]url = "https://api.getaria.cloud/mcp/w/wsp_YOURAPP"bearer_token_env_var = "ARIA_MCP_KEY"default_tools_approval_mode = "prompt"disabled_tools = ["db_migrate"]
SideRuns onDecides
CodexYour computerWhich Aria tools it may call, and whether it asks first
AriaAria’s serversLooking runs straight away. With a read key every Change waits. With an operate key routine ones run, and variables, launches, DNS records and GitHub push wait. Deleting waits for the typed name

How does AGENTS.md reach Codex?

Codex builds its instructions from AGENTS.md files, from the project root down, and the closest file wins.

OpenAI’s documentation says Codex reads one file per folder, joins them from the root down, and stops adding once the combined size reaches 32 KiB by default. Files nearer your current folder come later and override earlier ones.

For a repository with several services, keep the short Aria section that aria init writes at the root, and put service-specific notes in an AGENTS.md inside that service’s folder. An AGENTS.md never needs a key, a password or any secret value.

What does a first session look like?

  1. Check the server is listed

    Run codex mcp list. aria-myapp should be there.

  2. Ask for the file

    Paste the prompt below. Codex reads the repository, writes aria.yaml, checks it and saves it.

  3. Enter secrets and launch

    You pick the plan, pay and type secret values in Aria. Launching and changing variables wait for your approval. Run aria deploy --wait once it is approved.

  4. Iterate

    Ask Codex to run aria check, read the logs and fix what fails.

First prompt
Call get_stack_prompt, read this repository, write aria.yaml, check it with validate_stack_file, then save it with submit_stack_file. Ask me to enter any secret values; never print them.

Questions about Codex and Aria

Can Aria AI use my Codex subscription?

Yes, on the Mac. Aria finds Codex on your Mac, shows who it is signed in as and asks “Is this the one?”. One click connects it, and the turns run on your own Mac. In the browser, Aria AI uses an API key instead.

How do I add Aria to Codex?

Run aria login and then aria mcp add --agent codex. You approve a key in Aria, and the command adds the server to ~/.codex/config.toml and sets the file so only you can read it. By hand, add a mcp_servers table with the Aria address as its url and the name of an environment variable that holds your key as bearer_token_env_var.

Where does Codex keep its MCP settings?

In ~/.codex/config.toml, one table per server. OpenAI’s documentation says the desktop app, the command line and the IDE extension share that file. Check the list with codex mcp list.

Can I stop Codex calling some Aria tools?

Yes, in Codex. OpenAI’s documentation describes enabled_tools and disabled_tools for a server, and an approval mode per server or per tool. Aria’s own levels still apply on top: variables, launches, DNS records and deletes wait for you in Aria.

Does Codex read the AGENTS.md that aria init writes?

Yes. OpenAI’s documentation says Codex reads AGENTS.md files from the project root down to the folder you are in, with files closer to you coming later and overriding earlier ones. aria init adds a short Aria section to AGENTS.md.

Let Codex ship it

Sign up, connect Aria AI, or connect Codex and paste the first prompt.

Get your serverAll coding agents

Account · Terms

We’ve updated our terms.

Please read and accept the current terms of service and privacy policy to keep using Aria.