StatsHawk

View saved version →

---
name: statshawk-mcp
description: |
  Drive the StatsHawk hosted MCP server during an agent session —
  which tool to call, how to chain ids, and how to recover from OAuth
  or quota failures.
---

# StatsHawk MCP (data tools)

Endpoint: `https://mcp.statshawk.ai/mcp` (Streamable HTTP, OAuth)

## When to use

Use this skill when the agent itself needs sports data **right now**.
For product-code integration, switch to
[`../build/SKILL.md`](https://statshawk.ai/agent-onboarding/build/SKILL.md).
For finished artifacts, switch to
[`../workflows/SKILL.md`](https://statshawk.ai/agent-onboarding/workflows/SKILL.md).

## Install (if missing)

```bash
claude mcp add --transport http statshawk https://mcp.statshawk.ai/mcp
```

Other clients: https://statshawk.ai/docs/mcp/client-setup

On first tool call the client opens OAuth. The human signs in once; no
API key is pasted into MCP config.

## Tool routing

| Need | Tool | Notes |
| --- | --- | --- |
| Find a player | `search_player` | Returns `person_id` for chaining |
| Find games | `search_games` | Filter by league, date, team, status |
| Box score | `get_box_score` | Needs a game / contest id |
| Standings | `get_standings` | League slug e.g. `nba` |
| Roster | `get_team_roster` | Current roster + person ids |
| MLB matchups | `get_mlb_matchups` | Pregame pitching / lineup context |
| MLB PBP / Statcast | `get_play_by_play` | Filterable per player |
| Prop card / hit rates | `get_player_props` | **Paid plan** |
| What can I ask? | `get_stat_capabilities` / `search_docs` | When unsure |

Full catalog: https://statshawk.ai/docs/mcp/tool-catalog.md

## Default flow

1. **Discover** with `search_player` or `search_games`
2. **Fetch** with the returned ids (`person_id`, contest/game ids)
3. **Analyze** with `get_player_props` only when the account is paid
4. **Cite** ids in the answer so the human can verify

## Failure recovery

- **OAuth window never appeared** — look for a queued sign-in prompt; or
  remove and re-add the MCP server
- **`403 TIER_REQUIRES_PAID`** — analysis tools need any paid plan; use
  game logs / free tools instead, or ask the human to upgrade
- **`429 QUOTA_EXCEEDED`** — monthly units exhausted; tell the human to
  check https://statshawk.ai/dashboard
- **Connected but empty** — confirm league slug and date window; offseason
  standings still resolve to a concrete `season_year`

## Auth & quotas

https://statshawk.ai/docs/mcp/auth-and-quotas.md

View saved version →

---
name: statshawk-workflows
description: |
  Route a user request to a StatsHawk deliverable workflow — prop slate
  briefs, matchup memos, standings digests — and produce a finished artifact.
---

# StatsHawk workflows

Use this when the goal is a **finished artifact**, not raw tool output and
not product-code integration.

## Router

| User intent | Workflow |
| --- | --- |
| Props / lines / hit rates for a slate | [`prop-slate.md`](https://statshawk.ai/agent-onboarding/workflows/prop-slate.md) |
| Pitcher vs team / pregame MLB card | [`matchup-memo.md`](https://statshawk.ai/agent-onboarding/workflows/matchup-memo.md) |
| Who is on top / playoff picture | [`standings-digest.md`](https://statshawk.ai/agent-onboarding/workflows/standings-digest.md) |
| Unclear | Ask one short clarifying question, then pick the closest workflow |

## Shared rules

1. Confirm the artifact shape if ambiguous (length, audience, league)
2. Pull evidence via MCP ([`../mcp/SKILL.md`](https://statshawk.ai/agent-onboarding/mcp/SKILL.md))
   or REST ([`../build/SKILL.md`](https://statshawk.ai/agent-onboarding/build/SKILL.md))
3. Cite `person_id` / contest ids under claims
4. Parallelize independent players or games
5. End with a **Rerun inputs** block (league, date, player list, lines)

## If the request shifts

- Needs durable product code → Path B / build skill
- Auth missing → have the user reconnect the StatsHawk app (sign-in window opens on connect)
- Human unavailable → Path F (docs only; do not invent numbers)

Referenced files: 3