## Auth [#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. [#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 [#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](/dashboard).