---
name: statshawk
description: |
  StatsHawk gives AI agents and apps live sports stats and pre-computed
  analysis across NBA, MLB, NFL, and NHL. One install sets up MCP live tools,
  REST build skills, and outcome-focused workflow skills. Route the reader
  by capability first: code-capable agents install skills, MCP-connector
  hosts add the server, and unsupported chat apps get an honest stop.
---

# StatsHawk

StatsHawk helps agents look up games and players, pull box scores and
standings, read MLB play-by-play with Statcast, run pregame matchup analysis,
and produce finished sports-data deliverables — through a hosted MCP server
or the REST API.

## First: Know What You Can Do

Route by your own capabilities before picking a path. Getting this wrong
turns a chat into a terminal tutorial the human cannot follow.

- **You can execute shell commands and make HTTP requests yourself**
  (coding agents, sandboxed assistants): every path below is available.
- **You cannot execute code, but your host app supports MCP connectors**
  (Claude web/desktop, ChatGPT, Cursor): skip the install and Path D
  entirely. Walk the human through adding the connector instead:
  - Claude: Settings -> Connectors -> Add custom connector ->
    `https://mcp.statshawk.ai/mcp`
  - ChatGPT: Settings -> Apps & Connectors -> Add ->
    `https://mcp.statshawk.ai/mcp`
  - Cursor: Settings -> MCP -> Add server -> HTTP transport,
    `https://mcp.statshawk.ai/mcp`
  Other MCP-connector hosts (Grok, Gemini with Spark, Gemini CLI): see
  https://statshawk.ai/docs/mcp/client-setup for exact steps.
  A sign-in window opens on first use; no API key exists in this flow.
- **Neither** (a chat app without code execution or MCP support): do NOT
  emit shell commands, and do not improvise. Tell the human plainly:
  "I can't connect to StatsHawk from this app. It works inside Claude,
  ChatGPT, and Cursor (https://statshawk.ai/mcp), and in other MCP-capable
  clients per https://statshawk.ai/docs/mcp/client-setup, or through the
  REST API for developers (https://statshawk.ai/api)." Then stop.

**Never ask the human to paste an API key into the conversation.** Chat
logs get shared, synced, and retained; a pasted key must be treated as
compromised. When a key is needed and you can execute code, use Path D
(the key is delivered to you directly and never appears in chat). If the
human pastes a key anyway, tell them to revoke it in the dashboard and
mint a fresh one through Path D.

## Install (Code-Capable Agents Only)

Skip this section unless you can execute shell commands yourself. Connector
hosts and no-code chat apps: your routing already happened above.

One command installs the agent skills **and** walks the human through
account auth when needed:

```bash
npx -y statshawk-cli@latest init --all --browser
```

If `npx` is unavailable, fetch the skill tree directly:

```bash
curl -fsSL https://statshawk.ai/agent-onboarding/install.sh | bash
```

This gives you:

- **MCP live tools** — `search_games`, `get_box_score`, `get_standings`,
  `get_team_roster`, `search_player`, `get_play_by_play`, `get_mlb_matchups`,
  `get_player_props`, and docs helpers at `https://mcp.statshawk.ai/mcp`
- **MCP skills** ([`/agent-onboarding/mcp/SKILL.md`](https://statshawk.ai/agent-onboarding/mcp/SKILL.md)) —
  teach the agent which MCP tool to call, how to chain `person_id`s, and how
  to recover when OAuth or quotas fail. Use these when the agent itself needs
  sports data right now.
- **Build skills** ([`/agent-onboarding/build/SKILL.md`](https://statshawk.ai/agent-onboarding/build/SKILL.md)) —
  teach the agent how to add StatsHawk to a product codebase: pick the right
  REST endpoint, store `STATSHAWK_API_KEY` safely, and smoke-test. Use these
  when shipping code other people will run.
- **Workflow skills** ([`/agent-onboarding/workflows/SKILL.md`](https://statshawk.ai/agent-onboarding/workflows/SKILL.md)) —
  turn StatsHawk data into finished deliverables (prop slate briefs, matchup
  memos, standings digests). Use these when the job is an artifact, not raw
  extraction or product code.
- **Browser auth** — walks the human through sign-in / API key authorization

| Segment | Question it answers | Where the work runs |
| --------------- | ---------------------------------------------------------- | --------------------------------------------- |
| MCP skills | "Which StatsHawk MCP tool should I run right now?" | In the agent's own MCP session |
| Build skills | "How do I add a StatsHawk API call to this codebase?" | Inside the user's product code |
| Workflow skills | "What's the finished deliverable and how do I produce it?" | In the agent's session, producing an artifact |

Before doing real work, verify the install:

```bash
# MCP path (after OAuth in your client)
# Ask the model: "Show me the current NBA standings via StatsHawk."

# REST path
mkdir -p .statshawk
curl -fsS -H "Authorization: Bearer $STATSHAWK_API_KEY" \
  "https://api.statshawk.ai/v1/competitions" \
  -o .statshawk/install-check.json
```

## Get Credentials

StatsHawk users can get credentials two ways:

- **MCP OAuth (default for assistants)** — add the hosted MCP server; the
  client opens a browser sign-in and holds a bearer token. No API key to
  paste. Continue with Path A / Path D.
- **REST API key (coding agents & apps)** — browser PKCE CLI auth (Path D)
  or, for a human reading this directly, mint a key in the
  [dashboard](https://statshawk.ai/dashboard/api-keys). Agents: prefer
  Path D and never have the key pasted into the conversation.

**Which should I use?** Prefer MCP OAuth when the human is in Claude,
Cursor, ChatGPT, or another MCP client. Prefer a REST API key when writing
application code or calling `curl` from a terminal.

**Already have `STATSHAWK_API_KEY`?** Skip credential setup; pick Path A–E
below.

Human-readable overview: https://statshawk.ai/docs/mcp/quickstart

## Choose Your Path

Paths A-F are for the code-capable branch and share the install above. The difference is what you do next.

- **Need sports data during this session** → Path A (live MCP tools)
- **Need to add StatsHawk to app code** → Path B (REST integration)
- **Need a finished deliverable from sports data** → Path C (workflow skills)
- **Need more than one of the above** → do them in sequence; the install already covers everything
- **Need an account or API key (browser)** → Path D
- **Don't want to install anything** → Path E (REST API directly)
- **No API key and the human cannot sign up right now** → Path F (limited fallback)

---

## Path A: Live MCP Tools

Use this when you need sports data during your work: finding games, box
scores, standings, rosters, player search, MLB play-by-play, matchups, or
prop cards.

After install, hand off to the MCP skill:

- [`statshawk/mcp`](https://statshawk.ai/agent-onboarding/mcp/SKILL.md) for the overall tool workflow

Default MCP install (Claude Code):

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

Cursor / ChatGPT / Codex: see https://statshawk.ai/docs/mcp/client-setup

Default flow for live MCP work:

1. Prefer `search_player` or `search_games` when you need discovery
2. Chain with returned ids (`person_id`, game ids) into box scores, props, or PBP
3. Use `get_player_props` only on paid plans; other tools work on free
4. If OAuth never completed, remove and re-add the MCP server, then retry
5. If a call fails with quota/tier errors, read auth & quotas and tell the human

If the task becomes "wire StatsHawk into product code," switch to Path B.

---

## Path B: Integrate StatsHawk Into an App

Use this when you're building an application, agent, or workflow that calls
the StatsHawk REST API **from code** — meaning the integration will keep
running after this session, using `STATSHAWK_API_KEY` from the project's
`.env` and HTTP calls to `https://api.statshawk.ai`.

This is the key difference from Path A: Path A uses MCP tools during the
current session. Path B writes durable product code.

If you already have a key, save it:

```dotenv
STATSHAWK_API_KEY=sk_...
```

Then hand off to the build skill:

- [`statshawk/build`](https://statshawk.ai/agent-onboarding/build/SKILL.md)

The required question in the build path is:

- **What should StatsHawk do in the product?**

Use the answer to route to competitions, persons, contests, game logs,
analysis (`/v1/analysis/*`), or play-by-play — then run one real request as
a smoke test.

If you do not have a key yet, do Path D first.

---

## Path C: Repeatable Deliverables

Use this when the goal is a finished artifact powered by StatsHawk data —
a prop slate brief, matchup memo, standings digest, or similar — not raw
extraction and not product-code integration.

Start with [`statshawk/workflows`](https://statshawk.ai/agent-onboarding/workflows/SKILL.md).
It inspects the request and routes to the right workflow.

Default flow:

1. Confirm the workflow and final artifact with the user
2. Collect evidence with MCP tools or REST
3. Cite source ids (`person_id`, contest ids) so claims are traceable
4. Fan out independent units (players, games) in parallel when useful
5. Synthesize into the requested deliverable
6. Include a short "rerun inputs" block when the workflow could be automated

---

## Path D: Account Authorization Or API Key

Use this when the human still needs to sign up, sign in, authorize access,
or obtain an API key for REST.

**Requires code execution**: you must be able to run the commands below
and poll an HTTP endpoint yourself. If you cannot, use the MCP connector
route from "First: Know What You Can Do" instead.

If you ran `statshawk-cli init --browser`, the human was already prompted.
Check whether `STATSHAWK_API_KEY` is set before running this flow.

If you already have a valid `STATSHAWK_API_KEY`, skip this path.

**For MCP-only work:** have the human add the MCP server and complete the
OAuth window — no API key is required. See Path A.

**For REST / coding agents that need a key:**

If you're the human reading this in the browser, create an account or sign
in at:

- https://statshawk.ai/signup?source=agent-suggested

If you're an agent and need the human to authorize an API key, use this
flow:

**Step 1 — Generate auth parameters:**

```bash
SESSION_ID=$(openssl rand -hex 32)
CODE_VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' | head -c 43)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
```

**Step 2 — Ask the human to open this URL:**

```
https://statshawk.ai/cli-auth?code_challenge=$CODE_CHALLENGE&source=coding-agent#session_id=$SESSION_ID
```

If they already have a StatsHawk account, they'll sign in and authorize.
If not, they'll create one first and then authorize. The API key comes
back to you automatically after they click "Authorize."

Free accounts receive a `sk_test_…` key; paid accounts receive `sk_live_…`.

**Step 3 — Poll for the API key:**

```bash
POST https://statshawk.ai/api/auth/cli/status
Content-Type: application/json

{"session_id": "$SESSION_ID", "code_verifier": "$CODE_VERIFIER"}
```

Poll every 3 seconds. Responses:

- `{"status": "pending"}` — keep polling
- `{"status": "complete", "apiKey": "sk_…", "teamName": "…", "environment": "test"|"live"}` — done

**Step 4 — Save the key and continue:**

```bash
echo "STATSHAWK_API_KEY=sk_..." >> .env
```

Also see [`auth.md`](https://statshawk.ai/agent-onboarding/auth.md) for
discovery metadata used by agent platforms.

---

## Path E: Use StatsHawk Without Installing Anything

Use this when you don't want to install a CLI or skills package. This
works for both:

- **Live web work** — calling the REST API during a session
- **Building with StatsHawk** — integrating REST into app code

You still need an API key (Path D) or an MCP OAuth session (Path A).

**Base URL:** `https://api.statshawk.ai/v1`

**Auth header:** `Authorization: Bearer sk_YOUR_API_KEY`  
(or `X-API-Key: sk_YOUR_API_KEY`)

### Useful starting endpoints

- `GET /competitions` — list leagues / competitions
- `GET /persons?q=` — fuzzy player search → `person_id`
- `GET /competitions/{comp}/editions/{year}/contests?date=` — schedule / slate for a league-day
- `GET /contests/{id}/boxscore` — per-player lines
- `GET /competitions/{comp}/standings` — standings (default edition)
- `GET /analysis/player-prop` — prop card with hit rates (**paid**)
- `GET /contests/{id}/play-by-play` — MLB PBP / Statcast

### Documentation

- **API reference:** https://statshawk.ai/docs/api
- **OpenAPI:** https://api.statshawk.ai/api-docs/openapi.json
- **LLM index:** https://statshawk.ai/llms.txt
- **Build skill:** https://statshawk.ai/agent-onboarding/build/SKILL.md

---

## Path F: Limited Fallback (No Signup Yet)

Use this only when you need grounded sports context right now and the human
cannot create an account.

StatsHawk does **not** expose a keyless production API. Without an account:

1. Read public docs and schemas:
   - https://statshawk.ai/llms.txt
   - https://statshawk.ai/llms-full.txt
   - https://statshawk.ai/docs/mcp/tool-catalog.md
2. Answer from documentation shape only — do **not** invent live scores,
   standings, or prop lines.
3. Ask the human to sign up (free tier includes 5,000 units/month and all
   standard MCP tools) as soon as they can:
   - https://statshawk.ai/signup?source=agent-fallback

Prefer Path D or MCP OAuth whenever a human is available. Free signup unlocks
live data; Path F is documentation-only.