# 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](https://developers.openai.com/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](/pricing).
2. Codex installed. On Mac or Linux:

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

Windows users and npm users can follow the other install paths in the [Codex docs](https://developers.openai.com/codex/).

## 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`:

```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.


### Global scope (recommended)

Export your key, then add the server to `~/.codex/config.toml`:

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

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

`env_http_headers` maps the header name to the environment variable name, so Codex sends your key at request time and `config.toml` stays clean. Applies to every project on your machine.

### Project scope

Scope the server to one repository with a `.codex/config.toml` in the project root, using the same `[mcp_servers.roxy-astrology]` block. Codex only loads project config for trusted projects, so accept the trust prompt the first time you run `codex` in that directory, or set it in `~/.codex/config.toml`:

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

Keep `env_http_headers` so no teammate ever commits a key.

### Add all 12 domains

Paste your key once, then append every domain server to your global config:

```bash
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
```

All 12 Roxy MCP servers register at once. Run `codex mcp list` to confirm.


**Warning: `env_http_headers` reads the key from your environment at runtime, so `ROXY_API_KEY` must be exported in the shell that launches Codex. To hardcode the value instead, use `http_headers = { "X-API-Key" = "YOUR_KEY" }`, but then the key sits in plaintext in `config.toml`. Prefer the environment variable.**

## Step 3, verify the connection

List the configured servers:

```bash
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:

```bash
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](/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`:

```markdown
## 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](/docs/sdk "RoxyAPI TypeScript, Python, PHP, C#, and Go 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`:

```markdown
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 <a href="/AGENTS.md" target="_blank" rel="noopener" title="AGENTS.md execution playbook for AI coding agents - tight language-agnostic guide for Codex, Cursor, Claude Code, Windsurf, Gemini CLI">AGENTS.md</a> 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


### Does OpenAI Codex support remote MCP servers?
Yes. Codex connects to streamable HTTP (Remote) MCP servers configured with a `url` key in `config.toml`, alongside local stdio servers. RoxyAPI runs Remote MCP over streamable HTTP, so there is no local process to install or keep running, and the same config works across the Codex CLI, the IDE extension, and the ChatGPT desktop app.

### How do I pass my RoxyAPI key to a Codex MCP server?
RoxyAPI authenticates with the `X-API-Key` header. In `config.toml`, set `env_http_headers = { "X-API-Key" = "ROXY_API_KEY" }` so Codex reads the value from your environment at request time and the key never sits in the file. A static `http_headers` map also works but stores the key in plaintext.

### Can Codex read the RoxyAPI AGENTS.md?
Yes. Codex reads `AGENTS.md` from your project root natively as standing instructions. Every RoxyAPI SDK ships an `AGENTS.md`, and the site-level playbook at https://roxyapi.com/AGENTS.md drops in for projects with no SDK installed, so Codex stops guessing endpoint names.

### Is RoxyAPI free to try with Codex?
The keyless docs MCP server at https://roxyapi.com/mcp/docs needs no key and returns documentation so Codex writes correct code before you pay. Live calls across all 12 domains need an API key from the [pricing page](/pricing), billed at a flat rate where 1 request equals 1 quota unit, every domain included.

## What to build next

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