OpenAI Codex astrology MCP setup

One TOML block hands Codex the whole RoxyAPI reference as a searchable tool. Add your key and it runs live calculations while it writes the code. Five minutes, no local process.

OpenAI Codex drives the terminal CLI, the IDE extension and the cloud agent from one config. RoxyAPI runs as a Remote MCP server over Streamable HTTP, so the keyless docs server answers every question about endpoints, fields and SDK methods, and a per-domain server pulls a real natal chart, horoscope or tarot spread mid-build. Codex also reads AGENTS.md natively, which is where the truth sources go.

Step 1, the docs server (keyless)

Codex stores MCP servers in ~/.codex/config.toml. Add:

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

The url key is what makes it a Streamable HTTP server; command would make it a local stdio process. That is one tool, search_docs, over the entire reference: endpoints, request and response fields, SDK methods, auth, integration steps. No API key, documentation only, never a live calculation.

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

Using roxy-docs, find the natal chart endpoint and show me how to call it with the TypeScript SDK.

Step 2, a domain server for live calls

Live calculations take your key in the X-API-Key header, one server per domain. env_http_headers maps a header name to an environment variable name, so the key is read at request time and never sits in the file.

export ROXY_API_KEY="your-key-from-roxyapi.com/account?tab=keys"

[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/account?tab=keys"

for p in astrology vedic-astrology forecast human-design chinese-astrology feng-shui mesoamerican-astrology vastu numerology kabbalah tarot biorhythm ayurveda 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

Get your API key, or mint another there. Inside a session, /mcp lists every active server with its tool count.

Step 3, point Codex at the truth sources

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

## RoxyAPI
- Search https://roxyapi.com/mcp/docs (tool: search_docs) before writing any RoxyAPI call. No MCP in this context? Fetch https://roxyapi.com/llms.txt instead.
- Read https://roxyapi.com/AGENTS.md in full before the first call: auth, the location rule, request body shapes, the error contract, the SDK for this language.
- Print request and response fields with jq from https://roxyapi.com/api/v2/openapi.json before using an endpoint, with the jq recipe in https://roxyapi.com/AGENTS.md. Generate types from that spec, never by hand.
- Base URL https://roxyapi.com/api/v2. Auth is the X-API-Key header read from ROXY_API_KEY, server side only.
- Every chart, horoscope, panchang, dasha and compatibility call needs latitude, longitude and timezone from GET /location/search?q={city}. Never ask a person for coordinates.
- A 200 is clean JSON with no wrapper. Errors are { error, code, doc_url }, and a 400 carries issues[]. Retry only 429 and 5xx.
- Add ?lang= for en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.

For preferences you want on every repository, put the same block in ~/.codex/AGENTS.md. Every SDK also ships the playbook inside the installed package, so a TypeScript project can point at node_modules/@roxyapi/sdk/AGENTS.md from the root file.

Step 4, copy the prompt for what you are building

Every app prompt lives on one page: AI prompts. Adding a feature to a repo you already have is the Add RoxyAPI to an existing app prompt; a whole app from a blank repository is Astrology Birth Chart App or the domain prompt beside it.

Frequently asked questions