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.
| Class | Weight | Examples |
|---|---|---|
| Raw lookup / list | 1× | search_player, get_standings |
| 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 |
| Analysis cards | 10× | get_player_props, get_country_matchup |
Paid-tier gating
Analysis tools — get_player_props and get_country_matchup — 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.