<!-- https://predictabl.tech/docs/agents/ -->
# AI agents and MCP

There are two ways an AI agent works with Predictabl:

| | The agent… | Use |
|---|---|---|
| **An assistant answers questions** | calls your trained models as tools: "which customers are most likely to churn this month?" | The MCP server (below) |
| **A coding agent writes code** | builds and scores models in your project with the Python library | The docs as Markdown, and an `AGENTS.md` note (below) |

## Connect an assistant over MCP

The Python library includes an MCP server. It runs on your machine and talks to
Predictabl with your token. Use a **Predictions only** token: the tools read
and predict, and never upload or train.

You need [`uv`](https://docs.astral.sh/uv/) installed (`uvx` comes with it).

### Claude Code

```bash
claude mcp add predictabl --env PREDICTABL_API_KEY=pk_... -- uvx --from "predictabl[mcp]" predictabl mcp
```

### Claude Desktop

In **Settings → Developer → Edit Config**, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "predictabl": {
      "command": "uvx",
      "args": ["--from", "predictabl[mcp]", "predictabl", "mcp"],
      "env": { "PREDICTABL_API_KEY": "pk_..." }
    }
  }
}
```

### Cursor

In `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (every project),
add the same `mcpServers` entry as for Claude Desktop.

### Any other MCP client

Run `uvx --from "predictabl[mcp]" predictabl mcp` over stdio, with
`PREDICTABL_API_KEY` set. For your own instance, also set
`PREDICTABL_BASE_URL=http://localhost:8000/api/v1`.

### Tools

| Tool | What it does |
|---|---|
| `list_models` | Your trained models: what each predicts, its test metric |
| `get_model` | One model: what its number means, its kind, how well it tested, top features |
| `predict` | Score from your data: forecasts from the latest data or a date; event models by date window; filters, extra columns, one entity |
| `predict_rows` | Score records the agent passes in (up to 1,000 per call) |
| `top_risks` | The entities a classifier scored highest on its test, with the real outcome next to each |
| `top_forecasts` | The highest (or lowest) forecasts across every entity |
| `get_forecast` | The forecasts made at training time |
| `get_backtest` | Predicted against actual on held-out data, for one entity |
| `list_connections` | Your datasets (needs a Full access token) |
| `account` | Your plan and what is left of it |

### Things to ask

- "List my Predictabl models and tell me which one I can trust most."
- "Which 10 customers are most likely to churn, and how good is that model?"
- "Forecast sales for store 12 for the next two weeks. What date is the forecast from?"
- "Would a customer on a month-to-month contract paying 90 a month churn?"

## Help a coding agent build with Predictabl

Point the agent at the whole documentation as one Markdown file:

```text
https://predictabl.tech/docs/llms-full.txt
```

Each page also exists as Markdown at its own address plus `.md` (for example
[`/docs/predictions.md`](https://predictabl.tech/docs/predictions.md)), and
[`/docs/llms.txt`](https://predictabl.tech/docs/llms.txt) lists them all.

To make it stick in a project, add this to the project's `AGENTS.md` (or
`CLAUDE.md`):

```markdown
## Predictabl

This project uses Predictabl (`pip install predictabl`) for predictive models.
Docs for agents: https://predictabl.tech/docs/llms-full.txt

- Read the key from the PREDICTABL_API_KEY environment variable. Never write a
  key into code, tests, notebooks or commits.
- Build: `data = pb.connect(path_or_database_url)`, then `plan = data.plan(question)`. Show the
  user `print(plan)` (target, features, exclusions) before `plan.train()`.
  Each new question uses credits; check `pb.account()["credits"]` first.
- Score: check `model.kind` first. `flat` needs `rows=`; `event` scores rows
  dated today unless given `since`/`until`/`since_days`; `forecast` projects
  from the latest data (`preds.as_of` says from when).
- Always report `preds.meaning` with the numbers, and `preds.as_of` for
  forecasts. For multiclass models use `predicted_class`, not `prediction`.
- Errors are `predictabl.PredictablError` subclasses with `.code` and a message
  that says what to do: show the message to the user rather than retrying.
```

### Rules of thumb for agents

- **Plan before you train.** `data.plan()` is cheap to read and catches a wrong
  target before credits are spent; `data.predict()` skips that review.
- **Do not loop new questions.** Each one uses credits and a model slot. Refine
  the plan instead of asking again.
- **Use `fast_preview` to check a plan,** then train for real.
- **A `LimitReached` error is not transient.** Retrying will not help; the
  message says what will (the user's own AI key, or an upgrade).
- **An empty result is an answer.** Read `preds.note` before widening the window.
