OpenAI Codex, connect Roxy as an MCP server

Register Roxy once in config.toml, then ask Codex to build spiritual-data features in natural language. Remote MCP, no local server to run. Time to ship: 5 minutes.

OpenAI Codex is OpenAI's agentic coding tool. One account and one config drive the terminal CLI, the IDE extension, and the cloud agent in ChatGPT. Codex connects to RoxyAPI as a Remote MCP server over streamable HTTP, so it reads the entire Roxy reference and writes correct integration code with the right endpoints and field names the first try. Start with the keyless docs server, then add a per-domain server (for example /mcp/tarot) to make live calls while you build. No local process, no manual tool definitions, no glue code.

Because Codex reads AGENTS.md natively, the same playbook that ships inside every Roxy SDK drops straight into your project as persistent build context.

What you can build with this

• Natal chart components wired end-to-end ("build me a React birth chart page")
• Daily horoscope routes with the right endpoint and response shape
• Tarot reading apps with spread selection and card imagery
• Vedic kundli and Gun Milan features for matrimonial products
• Numerology Life Path calculators, dream-symbol lookups, I Ching hexagram casters
• Any multi-domain companion where the agent picks the right tool per question, a transit, a tarot pull, or a nakshatra, across all 12 domains under one key

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page.
2. Codex installed. On Mac or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows users and npm users can follow the other install paths in the Codex docs.

Step 1, add the docs server (keyless)

The docs server is the on-ramp for Codex. It searches the entire Roxy reference so the agent writes correct integration code with the right endpoints and field names the first try. No API key needed, it returns documentation, never live calls.

Codex stores MCP servers in config.toml. Add the docs server to ~/.codex/config.toml:

[mcp_servers.roxy-docs]
url = "https://roxyapi.com/mcp/docs"

Run codex mcp list to confirm, then start Codex. Now just ask in plain language:

using roxy-docs, integrate the RoxyAPI insight endpoints into my project

It reads the reference and wires up the endpoints, SDK calls, and types for you. No glue code, no guessing.

Step 2, add domain servers for live calls (optional)

The docs server teaches Codex how to build. To let the agent run real readings while you build, like a live tarot draw or a real natal chart, add the per-domain servers. These make live calls, so they take your API key in the X-API-Key header. Codex reads that value from an environment variable with env_http_headers, so the key never sits in the config file.

export ROXY_API_KEY="your-key-from-roxyapi.com/pricing"

[mcp_servers.roxy-astrology]
url = "https://roxyapi.com/mcp/astrology"
env_http_headers = { "X-API-Key" = "ROXY_API_KEY" }

[projects."/absolute/path/to/your/project"]
trust_level = "trusted"

export ROXY_API_KEY="your-key-from-roxyapi.com/pricing"

for p in astrology vedic-astrology numerology tarot human-design forecast biorhythm iching crystals dreams angel-numbers location; do
  cat >> ~/.codex/config.toml <<EOF

[mcp_servers.roxy-$p]
url = "https://roxyapi.com/mcp/$p"
env_http_headers = { "X-API-Key" = "ROXY_API_KEY" }
EOF
done

Step 3, verify the connection

List the configured servers:

codex mcp list

You should see roxy-docs plus any domain servers you added. Start Codex, then run /mcp in the terminal UI to see every active server with its tool count.

Out-of-band smoke test:

curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: $ROXY_API_KEY"

If that prints JSON, the key is fine. If it returns 401, re-check at your account.

Step 4, first prompt to try

Inside Codex, try one of these natural-language requests. Codex picks the right tool and wires it into real code.

• Draw me a tarot card.
• What is the daily horoscope for Aries?
• Look up dream symbols related to water.
• Calculate the Life Path number for someone born 1990-05-12.
• Build me a birth chart component. Call the natal chart endpoint, inspect the response, and generate a typed component with planets, houses, and aspects.
• Add numerology compatibility to my dating app. Call the compatibility endpoint with two names and birth dates, then build the scoring UI.

Add Roxy context to AGENTS.md

Codex reads AGENTS.md from your project root as standing instructions on every prompt, so this is the highest-leverage place to teach it Roxy. Drop this block into your AGENTS.md:

## Roxy API
- Integration playbook: https://roxyapi.com/AGENTS.md
- Endpoint reference: https://roxyapi.com/llms.txt
- OpenAPI spec: https://roxyapi.com/api/v2/openapi.json
- Base URL: https://roxyapi.com/api/v2
- Auth: X-API-Key header (env: ROXY_API_KEY)
- MCP server: already configured, tools auto-discovered
- Multi-language: add ?lang=xx (supported: tr, de, es, hi, pt, fr, ru)
- For any chart endpoint, call roxy-location search first to geocode the city.
- Prefer IANA timezone strings (America/New_York) over decimal offsets.

All five SDKs ship AGENTS.md bundled, and Codex reads it wherever it sits in your project. For TypeScript projects, install @roxyapi/sdk and reference the bundled file from your root AGENTS.md:

See @node_modules/@roxyapi/sdk/AGENTS.md for the RoxyAPI build playbook.

For Python install roxy-sdk, for PHP roxyapi/sdk, for C# RoxyApi.Sdk, and for Go github.com/RoxyAPI/sdk-go. Each ships the same AGENTS.md inside the installed package. Or point Codex at the site-level AGENTS.md at https://roxyapi.com/AGENTS.md if no SDK is installed. It is the tight, language-agnostic execution playbook with Rule 0, common task body shapes, and the field gotcha table.

Codex then understands every endpoint, parameter, and response shape on every prompt.

Gotchas

• config.toml, not JSON. Codex stores MCP servers in TOML at ~/.codex/config.toml, not a .json file. The transport follows the key you set: url means streamable HTTP (Remote MCP), command means a local stdio process. Roxy is always url.
• Project config needs trust. A project-scoped .codex/config.toml is ignored until the project is trusted (the first-run prompt, or trust_level = "trusted"). Until then Codex silently skips it.
• Export the key first. env_http_headers reads ROXY_API_KEY from the shell that launched Codex. Run echo $ROXY_API_KEY in the same terminal to confirm before starting.
• X-API-Key, not Authorization Bearer. Roxy uses a custom header. Use http_headers or env_http_headers, never bearer_token_env_var, which sends Authorization: Bearer.
• /mcp panel shows failed. Test the URL with curl https://roxyapi.com/mcp/astrology -H "X-API-Key: YOUR_KEY". A 405 confirms the URL is reachable (the MCP endpoint is POST only). 401 means the key is wrong.
• Geocode first for chart endpoints. Natal chart, kundli, panchang, and synastry all need latitude, longitude, and timezone. Tell Codex to call roxy-location first.

Frequently asked questions

What to build next

• The MCP setup docs cover every other MCP client (Cursor, Claude Code, Antigravity, OpenAI Agents, Gemini Agents).
• The Claude Code guide uses the same servers in the Anthropic terminal agent.
• The Cursor guide uses them in the Cursor editor.
• The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
• The API reference lets you explore endpoints before asking Codex to wire them up.