Codex CLI

Connect the AstroWay API to Codex CLI over MCP. Codex uses the local stdio package, configured in a TOML file.

Prerequisites

Get an API key in the dashboard. For free testing use a sandbox aw_test_* key — it doesn’t spend credits.

Setup

Edit ~/.codex/config.toml. Add the block below and restart Codex CLI. Auth is via env var, offline-ready:

~/.codex/config.toml

[mcp_servers.astroway]
command = "npx"
args = ["-y", "@astroway/mcp"]
env = { ASTROWAY_API_KEY = "aw_live_YOUR_KEY" }

Verify

Tell Codex in chat: “List the AstroWay tools” — or ask it to call a free reference tool, such as fetching the list of zodiac signs. If a result comes back, the connection works.

Troubleshooting

• 401 / invalid key — make sure the key is prefixed aw_live_* or aw_test_* and isn’t revoked. Check it in the dashboard.
• Tools don’t appear — fully restart Codex CLI and verify the path to ~/.codex/config.toml.
• -32602 validation errors — update the package: npm i @astroway/mcp@latest. Schemas are regenerated from the live spec.

See all clients — Agent setup.