# Use okdata in Codex: social data through MCP

> Add okdata to Codex's config.toml once, and the CLI, the IDE extension and the ChatGPT desktop app can all look up endpoints and fetch public social data.

Canonical page: https://okdata.online/integrations/codex/

With this set up, Codex can check real data before it writes code that depends on it. Picture a weekly report on how viewers react to a competitor's YouTube launch video. You ask Codex to fetch one page of comments through okdata, look at what comes back, then write a small script that does the same every Monday over the plain HTTP API and saves a CSV. The exploring happens over MCP; the script it leaves behind needs no AI at all.

## Before you start

- Codex installed: the CLI (`codex` runs in a terminal), the IDE extension, or the ChatGPT desktop app. All three read the same configuration, so you set this up once.
- An API key from okdata, starting with `okd_`. New keys come with $0.10 of credit. The [quickstart](/docs/quickstart/) explains how to get one.
- The key in the `OKDATA_API_KEY` environment variable. On a Mac, add this to `~/.zshrc` (Linux: `~/.bashrc`) and open a new terminal:

```bash
export OKDATA_API_KEY="okd_..."
```

## Add the server

Open `~/.codex/config.toml` (create it if it doesn't exist) and add:

```toml
[mcp_servers.okdata]
url = "https://api.okdata.online/mcp"
bearer_token_env_var = "OKDATA_API_KEY"
```

`bearer_token_env_var` names the variable, not the key. Codex reads `OKDATA_API_KEY` when it connects and sends `Authorization: Bearer <key>`, so the key never lands in the file. To limit the server to one project, put the same lines in `.codex/config.toml` inside that project instead; Codex only reads project files in projects you have marked as trusted.

In the IDE extension and the desktop app you can also add servers from the settings (**MCP servers**, then **Add server**, choosing **Streamable HTTP**), but the bearer-token setting lives in `config.toml`, so editing the file is the quickest way. Restart the extension or the app afterwards.

## Check that it worked

From a terminal, `codex mcp list` should show `okdata` with its URL. Inside a Codex session, type `/mcp` to see it connected with four tools: `find`, `describe`, `call` and `account`.

Then ask: "What is my okdata balance?" A number back means the key works, and the check is free.

## A first prompt to try

```text
Use okdata to find the YouTube video comments endpoint and tell me its price.
Fetch one page of top comments for https://www.youtube.com/watch?v=<video id>.
Then write comments_weekly.py that makes the same request over plain HTTP,
reads the key from the OKDATA_API_KEY environment variable, and saves a CSV.
```

## What it costs

`find`, `describe` and `account` are free. Each `call` costs the endpoint's price. One page of YouTube comments is $0.004, so the prompt above costs $0.004 plus whatever you later spend running the script. A page of [Xiaohongshu note search](/apis/xiaohongshu/notes/search/) is $0.02. Failed calls are free.

If you run Codex with broad auto-approval, include a budget in the prompt, such as "no more than two paid calls".

## When something goes wrong

- **`unauthorized` (401).** Codex could not read the key. Start Codex from a terminal where `[ -n "$OKDATA_API_KEY" ] && echo set || echo missing` prints `set`. Apps opened from the Dock or Start menu may not see variables set only in your shell profile, so the desktop app can fail where the CLI works. As a last resort, replace the `bearer_token_env_var` line with `http_headers = { "Authorization" = "Bearer okd_..." }`; the key then sits in plain text in `~/.codex/config.toml`, so never do this in a project's `.codex/config.toml`.
- **`insufficient_balance` (402).** Not enough balance for the call; nothing was charged. Top up and retry. Prices are on the [pricing page](/pricing/).
- **`rate_limited` (429).** Too many calls at once. The error includes `retry_after_seconds`; wait and repeat the same call. No charge.
- **The server or its tools are missing.** Check the TOML: the section header must be `[mcp_servers.okdata]` with an underscore, and the URL must end in `/mcp`. If the server is slow to start on a poor connection, add `startup_timeout_sec = 30` under it.

## Read next

- [The MCP server](/mcp/): the four tools and what to tell the agent.
- [YouTube video comments](/apis/youtube/videos/comments/list/): parameters, fields and price.