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 installed (uvx comes with it).
Claude Code
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:
{
"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:
https://predictabl.tech/docs/llms-full.txt
Each page also exists as Markdown at its own address plus .md (for example
/docs/predictions.md), and
/docs/llms.txt lists them all.
To make it stick in a project, add this to the project's AGENTS.md (or
CLAUDE.md):
## 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_previewto check a plan, then train for real. - A
LimitReachederror 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.notebefore widening the window.