Auth & Quotas
How sign-in works, what each tool costs, and which tools need a paid plan.
Auth
The MCP server is hosted. You don't paste an API key into client config. On first connect, your MCP client runs an OAuth sign-in against your Statshawk account and holds a bearer token for the session. Tool calls are metered against the same account and monthly unit quota as your REST API keys.
Not every call costs the same.
Calls are metered in units with weights by class. Light lookups are cheap; analysis is the premium tier. Odds: discovery 1× · spot board 5× · history page 10×.
| Class | Weight | Examples |
|---|---|---|
| Raw lookup / list | 1× | search_player, get_standings, get_odds_markets |
| Gamelog / box score / season stats | 2× | get_box_score, search_games |
| Rosters, matchup boards | 3× | get_team_roster, get_mlb_matchups |
| Play-by-play, Statcast | 5× | get_play_by_play |
| Odds spot board | 5× | get_odds_spot |
| Odds history page | 10× | get_odds_history |
| Analysis cards | 10× | get_player_props |
History is 10× per page, not per tick. REST paging, filters, and interval are on
Quotas · Odds history pages
(data.truncated / data.next_cursor, not meta).
MCP get_odds_history is contest-scoped: contest_id is always required. Optional
person_id scopes a player-prop tape to that person on the same contest; it does not
wrap unscoped person history. MCP limit defaults to 30 (max 50); REST history
is 50 (max 100). Prefer cursor=data.next_cursor (tie-safe). before /
data.next_before is a timestamp window only and can skip same-time leftovers.
Paid-tier gating
Analysis tools (currently get_player_props) require a paid plan. Free-tier accounts
receive a 403 (TIER_REQUIRES_PAID) on those calls; every other tool works on the
free tier.
When you hit your monthly unit cap the API returns 429 (QUOTA_EXCEEDED) until the
period resets or you upgrade. See your current usage and plan in the
dashboard.