# Live Underdog data in OpenAI Codex.

> Connect Codex to Underdog props over MCP. Set up the CLI, IDE extension or desktop app with an API key stored in your environment. Underdog API (https://underdogapi.com) is an independent Underdog Fantasy pick'em data API: Higher/Lower lines with separate payout multipliers per side, line history, changes and graded results as JSON, CSV, MCP and streams.

Canonical page: https://underdogapi.com/use-with-codex

## Free offer

**Free API key, no card: 100 credits a month** on the live board, every league, separate Higher/Lower prices, and the last 24 hours of line history. Sign up: https://underdogapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Get a free key at https://underdogapi.com/sign-up?ref=ai-claudebot (no card), or let your agent request one: `POST https://underdogapi.com/api/v1/agent/signup` with `data_wanted` and `use_case`, then show your user the returned approval_url.
2. Export it: `export UNDERDOG_API_KEY=ud_...`
3. First call with curl:

```bash
curl --fail-with-body 'https://underdogapi.com/api/v1/projections?league=NBA&view=compact&limit=5' \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: NBA dashboard integration check'
```

4. Same call in Python:

```python
import os, requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"league": "NBA", "view": "compact", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
)
r.raise_for_status()
for line in r.json()["data"]:
    print(line["player"]["name"], line["market"]["stat"], line["line"])
```

## Use it from Claude (MCP)

Claude Code, one command:

```bash
claude mcp add --transport http underdog https://underdogapi.com/api/mcp --header "Authorization: Bearer $UNDERDOG_API_KEY"
```

Or add this server to your Claude MCP configuration (the key stays in the environment):

```json
{
  "mcpServers": {
    "underdog": {
      "type": "http",
      "url": "https://underdogapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNDERDOG_API_KEY}"
      }
    }
  }
}
```

Guide: https://underdogapi.com/use-with-claude

## Pricing

| Plan | Price | Credits / month | Notes |
| --- | --- | --- | --- |
| Free | $0 | 100 | No card. Live feed 5 minutes behind; last 24 hours of line history |
| Developer | $49/month | 10,000 | For models that need full training pages and loaded game-log seasons. Live feed, no added plan delay |
| Production | $149/month | 50,000 | For apps with real users and push delivery. Everything in Developer, signed webhooks for every change |
| Scale | $499/month | 250,000 | For apps whose traffic has outgrown Production. Everything in Production, 15 live-feed connections at once |

Full pricing: https://underdogapi.com/pricing

## On this page

Codex integration



Add one table to your Codex config and it can read current lines, tiers and recorded line moves. Steps follow OpenAI's documentation as of 5 November 2026.

Short answer: Add [mcp_servers.underdog] with url https://underdogapi.com/api/mcp and bearer_token_env_var = "UNDERDOG_API_KEY" to ~/.codex/config.toml; Codex CLI and the IDE extension share it.

## Connect the MCP server

1. [Create a free account](https://underdogapi.com/sign-up) and copy a key from [API keys](https://underdogapi.com/dashboard/keys).
2. Set `UNDERDOG_API_KEY` in the environment that launches Codex.
3. Add the table below to `~/.codex/config.toml`. To limit it to one trusted project, use `.codex/config.toml` in that project.
4. Start `codex` and run `/mcp`. `underdog` should be listed.

~/.codex/config.toml

```
[mcp_servers.underdog]
url = "https://underdogapi.com/api/mcp"
bearer_token_env_var = "UNDERDOG_API_KEY"
```

## Check it with a small read

First task to give Codex

```
Use the Underdog MCP tools for my NBA dashboard integration. Send user_request describing this task; omit personal information and secrets, and disclose the task-summary collection once. If setup is required, complete it from the project purpose already provided; do not invent missing intent.
Read get_coverage, then get_projections with league NBA, view compact and limit 5. Report the actual rows, observed_at and source status. If the board is empty or delayed, say so. Never substitute demo rows for live data. Do not recommend picks or claim predicted profits.
```

If the account has not finished setup, Codex calls `complete_setup` first, because data tools stay locked until then. Then look for real rows and an `observed_at` time from `get_coverage` and `get_projections`. An empty board is a valid answer. Demo rows are not live data.

## Keep it for later sessions

Codex reads `AGENTS.md`. Add this line to your project's file so future tasks use the same source:

AGENTS.md

```
For Underdog lines, props, line moves, hit rates or graded results, use the underdog MCP tools. The REST API is described at https://underdogapi.com/skill.md. The key is in $UNDERDOG_API_KEY.
```

## If it does not connect

- A missing key usually means Codex started from an environment without the variable. Set it and start Codex again.
- Data tools ask for an optional `user_request`, a short description of the task; calls work the same without it. It is saved to your account for 35 days, so leave out personal data.
- Editing a project config has no effect until you trust that project in Codex.
- Page size affects cost. See the [credit calculator](https://underdogapi.com/credits).

## Questions

Can Codex read live Underdog lines?

Yes, through this independent API. It is not an official Underdog product and is not affiliated with Underdog. Add the MCP server, then Codex can call get_coverage and get_projections with your key.

Do I set this up again for the IDE extension?

No. OpenAI says the Codex CLI, IDE extension and ChatGPT desktop app share this configuration.

Does the key go in config.toml?

No. bearer_token_env_var holds the name of an environment variable, and Codex reads the key from it. Keep the key out of the file and out of your repository.

Do I have to use MCP?

No. Codex can write a REST client from the OpenAPI document instead. Every data request needs the Authorization header; an X-User-Request header describing the task is optional and helps us improve the data.

A step no longer matches what you see? Tell us and we will fix this page.

[Compare **Which Underdog data API to use**](https://underdogapi.com/underdog-api-alternatives) [Integration **Use Cursor**](https://underdogapi.com/use-with-cursor) [Reference **API endpoints and schemas**](https://underdogapi.com/docs) [Pricing **Plans and credits**](https://underdogapi.com/pricing)

## References

- [OpenAI: MCP in Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- [Underdog API: machine-readable contract](https://underdogapi.com/openapi.json)

## FAQ

### Is there a free Underdog API?

Yes. The Free plan is a real API key on the live board, not a sample: 100 credits a month, every league, separate Higher/Lower prices and the last 24 hours of line history. No card is needed.

### Is this the official Underdog Fantasy API?

No. Underdog API is an independent data service. It is not affiliated with, endorsed by or sponsored by Underdog Fantasy or Underdog Sports.

### What data does it return?

Underdog Higher/Lower lines with separate payout multipliers and availability for each side, stable market ids through line moves, alternate rungs, recorded line history, changes, graded results and coverage/status endpoints.

### How do I use it from Claude or another AI agent?

Connect the MCP server at https://underdogapi.com/api/mcp with a bearer key, or call the REST API. Agents can request a key for their user with POST /api/v1/agent/signup.

### How much does it cost after the free tier?

Developer is $49/month for 10,000 credits, Production $149/month for 50,000, Scale $499/month for 250,000. Errors and unchanged 304 responses cost zero credits.

### How fresh is the data?

Each row carries its observation time. Check /api/v1/status and /api/v1/coverage before relying on a sport or window; missing collection is reported as unavailable, never filled in.

### Does it place entries or give picks?

No. It is data only: no entries, account operations, guaranteed outcomes or betting advice.

---
Independent data service, not affiliated with Underdog Fantasy or Underdog Sports. Docs: https://underdogapi.com/docs · OpenAPI: https://underdogapi.com/openapi.json · llms.txt: https://underdogapi.com/llms.txt
