> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://statpad.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server.

# Build with AI

> The three Statpad tools for AI agents. Install the Statpad agent skill, connect the docs MCP server or read llms.txt, check the code your agent writes, and connect @statpad/mcp for live data.

Statpad has three tools for AI agents. Two of them help a coding agent, such as Claude Code, Cursor or Codex, write code that calls Statpad. The third gives an agent live game data while it runs.

| Tool                                        | What it does                                                                                                                     | Use it when                                                                           | Needs a key |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------- |
| [Statpad skill](#install-the-statpad-skill) | Teaches the agent the integration rules agents most often get wrong, such as resuming from `seq` and keeping keys on the server. | A coding agent writes or reviews Statpad code.                                        | No          |
| [Docs MCP server](#connect-the-docs)        | Lets the agent search these docs and read the answer with links to its sources.                                                  | A coding agent needs a field, a limit or an error code.                               | No          |
| [`@statpad/mcp`](/docs/mcp)                 | Gives the agent tools that read live schedules, scores, plays and box scores.                                                    | An agent answers questions about games, such as "Who has the ball in the Bills game?" | Yes         |

For a coding agent, install the skill and connect the docs. The skill carries the rules, and the docs carry the details the rules point to.

## Set up a coding agent

### Install the Statpad skill

The skill is a `SKILL.md` file in the [Agent Skills](https://agentskills.io) format. Install it with the [skills CLI](https://github.com/vercel-labs/skills), which needs Node.js 22.20 or newer:

```bash
npx skills add https://statpad.dev
```

The CLI finds the skill at `statpad.dev/.well-known/agent-skills` and asks which agents to install it for. It installs into the current project by default. Add `-g` to install it for every project.

Without the CLI, download the file into your agent's skills folder. For Claude Code, that's `~/.claude/skills` for every project or `.claude/skills` in one project:

```bash
mkdir -p ~/.claude/skills/statpad
curl -fsSL https://statpad.dev/.well-known/agent-skills/statpad/SKILL.md -o ~/.claude/skills/statpad/SKILL.md
```

The agent loads the skill when a task involves Statpad. Its rules cover:

* keeping keys on your server
* reading a game over REST, then subscribing from the response's `seq`
* replacing entities by `entity_type` and `entity_id`, and keeping the highest `version`
* resuming from the last applied seq, backing off, closing silent connections, and stopping on close code `1008`
* polling the changes feed on Developer, which has no stream
* pagination, dates and the TypeScript SDK

Each rule names the docs page with the detail. Read the whole skill at [statpad.dev/.well-known/agent-skills/statpad/SKILL.md](https://statpad.dev/.well-known/agent-skills/statpad/SKILL.md).

### Connect the docs

The docs MCP server at `https://statpad.dev/docs/_mcp/server` has one tool, `searchDocs`. The agent asks it a question and gets an answer drawn from these docs, with a link to each page it used. It needs no key.

**`Claude Code`**

```bash Claude Code
claude mcp add --transport http statpad-docs https://statpad.dev/docs/_mcp/server
```

**`Cursor`**

```json Cursor
{
  "mcpServers": {
    "statpad-docs": { "url": "https://statpad.dev/docs/_mcp/server" }
  }
}
```

**`Codex`**

```bash Codex
codex mcp add statpad-docs --url https://statpad.dev/docs/_mcp/server
```

For Cursor, add the entry to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in one project. Other clients take the same URL as a remote HTTP server.

An agent without MCP can read the docs directly:

* [`statpad.dev/docs/llms.txt`](https://statpad.dev/docs/llms.txt) lists every page, guides and API reference, with a one-line summary each.
* Every page has a Markdown version. Append `.md` to its URL, such as `https://statpad.dev/docs/streaming.md`.

### Ask for what you want

Describe the program in plain words, and name the league, the language and the library. For example:

```text
Write a TypeScript script with @statpad/sdk that follows tonight's NFL game over the Statpad stream and resumes after a disconnect.
```

The stream comes with Pro, Business and the Pro trial. On Developer, which is REST only, ask for a script that polls the game's changes feed instead. If no game is on, ask the agent to test the script against the recorded game on [Sample responses](/docs/replay#replay-the-game), which needs no key.

The skill steers the agent toward the client the [Quickstart](/docs/quickstart) builds by hand, with the four rules from [Live updates](/docs/streaming#stay-connected) added. In TypeScript, that's a script with the SDK and `ws` that finds tonight's game, reads it, subscribes from its `seq`, and applies each change. Review it before you run it, as you would any generated code.

## Check the agent's code

Compare what the agent wrote with [the whole client](/docs/streaming#the-whole-client) on Live updates. A correct client does each of these:

| Check                                                                                                                                                                                                                           | Where it is in the hand-written client                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Reads the key from the environment, on a server or your machine, never in a web page.                                                                                                                                           | [Set up](/docs/quickstart#set-up)                                                           |
| Subscribes after `welcome`. A client that keeps state starts from a snapshot, or fills its state from REST reads and resumes from the lowest `seq` among them. A client that only prints can resume from the game read's `seq`. | [Keep state](/docs/streaming#keep-state), [Follow it live](/docs/quickstart#follow-it-live) |
| Records the `seq` of each change after applying it, and resumes from it on reconnect.                                                                                                                                           | [Follow it live](/docs/quickstart#follow-it-live)                                           |
| Replaces entities by `entity_type` and `entity_id`, without merging fields.                                                                                                                                                     | [Keep state](/docs/streaming#keep-state)                                                    |
| Backs off between reconnects, with jitter, up to 30 seconds.                                                                                                                                                                    | [Back off between reconnects](/docs/streaming#back-off-between-reconnects)                  |
| Closes the socket after 20 seconds with no message.                                                                                                                                                                             | [Notice a dead connection](/docs/streaming#notice-a-dead-connection)                        |
| Handles stream errors by code. On `resync_required` and `invalid_resume`, subscribes again without `resume` and replaces its state with the snapshot.                                                                           | [Handle stream errors](/docs/streaming#handle-stream-errors)                                |
| Stops on close code `1008` instead of reconnecting.                                                                                                                                                                             | [Stop on close codes](/docs/streaming#stop-on-close-codes-that-wont-recover)                |

To test it, run the script during a game and turn off Wi-Fi for 30 seconds. The client should close the silent connection, retry with backoff until the network returns, then print the changes it missed, once each and in order. With no game on, [Sample responses](/docs/replay#replay-the-game) feeds a recorded game through the same change handler without a key.

Compare a Developer client that polls the changes feed with [Without the stream](/docs/streaming#without-the-stream). If it stores state, check that on `resync_required` it reads again everything it keeps, not just the game.

## Give an agent live data

[`@statpad/mcp`](/docs/mcp) is an MCP server with six read-only tools, such as `find_games`, `get_game` and `get_plays`. Every result about one game carries its `seq`, so the agent can ask for only what changed since. It runs on your computer and reads with your API key, on any plan. In Claude Code:

```bash
claude mcp add statpad -e STATPAD_API_KEY=sporty_... -- npx -y @statpad/mcp
```

[MCP server](/docs/mcp) covers the other clients, every tool and what each call costs.