gamedai-nfl-mcp

Part of gamedai, the interactive sports radio. This

MIT-licensed MCP server exposes five read-only NFL tools backed by the public

gamedai API.

The default backend is `https://gamedai-v2-preview.fly.dev`. Override it with

`GAMEDAI_API_BASE`. Scout calls optionally use `GAMEDAI_SCOUT_API_KEY`; the

legacy `GAMEDAI_PUBLIC_API_KEY` name is accepted as an alias.

Install

cd tools/gamedai-mcp
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[test]"

Tools

• `get_game_scores(date?, event_id?)` reads the public slate. `date` is sent

to the backend; `event_id` filters the returned slate locally.

• `get_wire_news(page?, page_size?)` reads the paginated Wire feed.
• `get_player_grade(player, season?, week?)` reads Scout player grades.
• `get_start_sit_recommendation(player_a, player_b, week, season?)` reads the

Scout start/sit comparison. `week` is required.

• `get_scout_rankings(position?, scoring?, week?)` reads the Scout rankings

board.

When `season` is omitted, `get_player_grade` and

`get_start_sit_recommendation` use the latest complete NFL stats season:

`today.year - 1` when the month is March or later, otherwise `today.year - 2`.

An explicit season always wins. Rankings derive their source season in the

backend.

All backend errors are returned as structured objects with `code`,

`http_status`, and a bounded `message`. Scout keys are sent only to

`/v1/scout/*` calls.

Hosted mode

The hosted service uses streamable HTTP:

gamedai-nfl-mcp --transport streamable-http --host 0.0.0.0 --port 8080

The MCP endpoint is `/mcp`; process liveness is `/healthz`; backend readiness

is `/readyz`. The Fly app is the existing `gamedai-mcp` app and deploys from

this directory with `flyctl deploy`.

The pinned MCP SDK enables stateless HTTP when its `FastMCP` constructor

supports `stateless_http=True`. Older SDKs keep normal sessions, as a safe

fallback.

Environment

export GAMEDAI_API_BASE="https://gamedai-v2-preview.fly.dev"
export GAMEDAI_SCOUT_API_KEY=""

`OPENAI_APPS_CHALLENGE_TOKEN` is only needed for the existing public Apps

challenge route. Never commit keys or expose the Scout key to an MCP model.

Tests

Tests use mocked HTTP clients and do not call the live backend:

pytest

The canonical backend contract is generated at

`backend/openapi/scout_public_contract.openapi.json`; run

`python scripts/mcp/check_contract_drift.py` from the repository root to check

for route or schema drift.

License: MIT.