# Connect Gemini CLI to Underdog data.

> Use Gemini CLI with Underdog data through Streamable HTTP MCP. Configure headers, discover tools, check live records and build an authenticated REST client. 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-gemini

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

Gemini CLI integration



Use MCP to query current projections and recorded line history, or generate a server-side client from the API contract. UnderdogAPI is an independent data service with labeled tiers, timestamps and source health.

Short answer: Add underdog under mcpServers in .gemini/settings.json with httpUrl https://underdogapi.com/api/mcp and an Authorization: Bearer header from UNDERDOG_API_KEY, then run /mcp in Gemini CLI.

## Configure Streamable HTTP

1. [Create your account](https://underdogapi.com/sign-up), copy a key from [API keys](https://underdogapi.com/dashboard/keys), and make `UNDERDOG_API_KEY` available in Gemini CLI's environment.
2. Merge this server into `~/.gemini/settings.json`. Preserve existing settings and server entries. Use the environment placeholder so the configuration does not contain the secret.
3. Restart Gemini CLI and run `/mcp` to inspect server status and discovered tools. Review tool permissions before the first call.

~/.gemini/settings.json · Gemini CLI

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

Use `httpUrl` for this endpoint. In Gemini CLI, `url` selects the separate SSE transport. The configuration here is for the CLI, not the Gemini website.

## Verify discovery and a live result

Task to give Gemini CLI

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

Look for `get_coverage` and `get_projections` in the discovered tool list. Gemini may display tools with a server-qualified name. Keep league and row limits narrow while checking the response. Public `search`, `fetch` and labeled demo tools can be used without a key; live data tools require authentication.

## Generate application code with Gemini

For an application integration, provide [OpenAPI](https://underdogapi.com/openapi.json) and ask for a server-side request function. Require explicit error handling, pagination only when needed, and preservation of `observed_at` and source-status fields. Keep API keys out of browser bundles.

Send a task summary in `X-User-Request` on authenticated REST data calls; MCP uses `user_request`. It is optional and never blocks a call. Derive it from the actual operation, omit personal data and secrets, and disclose once that summaries are retained for 35 days.

Small REST request to verify generated code against

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

## Evaluate the dataset before building around it

| Requirement | Evidence to inspect |
| --- | --- |
| Live player props and tiers | [Public league and player pages](https://underdogapi.com/props), then authenticated observations |
| Historical line movements | [Recorded sample and coverage calendar](https://underdogapi.com/data/history-sample); recording boundaries come from retained observations |
| Training labels | [Graded examples](https://underdogapi.com/data/graded-examples) and the leagues returned by coverage |
| Per-side payout prices | [Side-price data contract](https://underdogapi.com/docs#multipliers), including line and period |
| Operating budget | [Per-operation credit costs](https://underdogapi.com/credits) and [plan allowances](https://underdogapi.com/pricing) |

New accounts include 100 free credits per month. Developer costs $49 with 10,000 credits; Production costs $149 with 50,000; Scale costs $499 with 250,000. New accounts use credits. Check source health and available history for your workflow rather than assuming every league has identical depth.

## Working in Gemini web chat

Share a [public player or league page](https://underdogapi.com/props) and request a source-cited summary with its observation time. Alternatively, paste a board exported from your workspace. This provides a snapshot; refresh it when newer data is needed. Do not give the chat your API key.

## Questions

Can Gemini CLI connect to the Underdog API?

Yes. Add the MCP endpoint to Gemini CLI settings using httpUrl and an Authorization Bearer header. The CLI can discover tools for current projections, recorded line history, results and coverage.

Is Gemini CLI setup the same as Gemini web chat?

No. This configuration is for the developer CLI. In a web chat, provide a public player page or an exported board with observation times. Do not assume the web app accepts the same MCP settings, and never paste a secret key into a chat.

Why use httpUrl rather than url in Gemini settings?

Gemini CLI uses httpUrl for Streamable HTTP and url for SSE transport. UnderdogAPI exposes its MCP service through Streamable HTTP at https://underdogapi.com/api/mcp.

Can Gemini generate a REST client instead?

Yes. Give the coding task the OpenAPI contract and require server-side Bearer authentication plus X-User-Request. Review generated code against the contract and test a bounded read before deploying it.

[Runnable example **Build a comparison dashboard**](https://underdogapi.com/docs/league-workflows) [Integration **Use Claude Code**](https://underdogapi.com/use-with-claude) [Reference **API endpoints and schemas**](https://underdogapi.com/docs) [Get started **Create your free account**](https://underdogapi.com/sign-up)

## References

- [Google: MCP servers with Gemini CLI](https://geminicli.com/docs/tools/mcp-server/)
- [Google: Gemini CLI configuration](https://geminicli.com/docs/reference/configuration/)
- [UnderdogAPI: machine-readable API 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
