View as Markdown

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_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.