MCP — connect your AI

predictAI ships an official MCP server — a Model Context Protocol integration that lets AI agents (Claude, Cursor, ChatGPT connectors, or anything MCP-capable) operate the platform for you. Ask your assistant "upload this CSV and tell me if next week looks risky" and it composes the right API calls: ingestion, a goal, a forecast, an alert — no code, no docs-diving.

Everything in these docs is reachable through it: 39 curated, task-oriented tools covering signals, segments, goals, foundation models, pipelines, trainings, deployments, predictions, scenarios, alerts, and billing — including quick_forecast, which turns a raw CSV into a zero-shot forecast in a single tool call, and three wait tools that turn the platform's asynchronous jobs into single tool calls by listening on the realtime WebSocket stream.

Two ways to connect

Hosted — paste a URL

Add the endpoint to any MCP client:

https://mcp.predict.ai/mcp

On first use your browser opens a predictAI consent page. Enter your email, click the sign-in link we send you — the same login as the app — and pick the workspace the client may use, or create a fresh one right there (agents often deserve their own isolated space; brand-new accounts start with one this way too). Behind the scenes an API token named after the client (e.g. MCP — Cursor) is created in your account and sealed into the OAuth credential handed to the client. You never copy a token, and you stay in control: the token shows up under Settings → API tokens, and revoking it kills the grant instantly. (Prefer to bring your own token? There's a "paste an API token" option on the same page.)

In Cursor (~/.cursor/mcp.json) or any client that takes a URL:

{
  "mcpServers": {
    "predictai": { "url": "https://mcp.predict.ai/mcp" }
  }
}

Prefer to skip the browser flow? The hosted endpoint also accepts your API token directly as a Bearer credential:

{
  "mcpServers": {
    "predictai": {
      "url": "https://mcp.predict.ai/mcp",
      "headers": {
        "Authorization": "Bearer pa_live_...",
        "X-Workspace-Id": "ws_..."
      }
    }
  }
}

Local — run it yourself

The same server ships as an npm package for stdio-based clients. No infrastructure, talks to the normal REST API from your machine:

{
  "mcpServers": {
    "predictai": {
      "command": "npx",
      "args": ["-y", "predictai-mcp"],
      "env": {
        "PREDICTAI_TOKEN": "pa_live_...",
        "PREDICTAI_WORKSPACE_ID": "ws_..."
      }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add predictai -e PREDICTAI_TOKEN=pa_live_... -e PREDICTAI_WORKSPACE_ID=ws_... -- npx -y predictai-mcp

The tools

Tools are task-oriented, not endpoint-shaped — descriptions are written for agents, and results include "what to do next" hints.

Read-only tools (lists, gets, previews, analyses, and the wait tools) declare the standard readOnlyHint annotation, so MCP clients that auto-approve safe tools can run them without a confirmation prompt.

The one destructive tool, delete_signals, declares destructiveHint (clients that gate dangerous tools will ask before running it) and permanently removes every stored value for the selected signal keys and/or event streams. It follows the same safety net as the app: marketplace-subscribed (read-only) signals are skipped, and if a selected key is published on the marketplace nothing is deleted — the call returns a confirmation summary (listings, subscriber counts) and only proceeds when re-called with force=true.

The async story — wait tools

Trainings, CSV imports, and goal setup are asynchronous: the API returns an id immediately and the work happens in the background. Most platforms make agents poll. predictAI's MCP server instead subscribes to the realtime event stream and holds the tool call open until the terminal event arrives — an hour of tournament becomes one tool call from the agent's point of view.

Each takes a timeout_s (default 300). On timeout it doesn't fail — it returns "status": "still_running" with the latest progress and the agent simply calls it again. Before listening, each tool checks current state over REST, so an already-finished job returns instantly. And the socket is the fast path, not a single point of failure: a REST poll runs alongside it, so even if the realtime stream is unreachable or drops an event, the tool still answers — it can never hang.

While a wait is in flight the server streams MCP progress notifications (when the client sends a progressToken), so clients that reset their request timeout on progress — Cursor, Claude, and most modern MCP clients do — never abort a long wait. Cancelling the request on the client side stops the wait immediately.

What a session looks like

The shortest possible session is one tool call:

You: Here's stocks.csv — predict the close price in 5 days.

Agent: (calls quick_forecast with the CSV, target: "close", horizon: 120, interval_seconds: 3600)

The zero-shot forecast puts the close at ~103.4 in 5 days, with an 80% band of 98.1–108.9.

One call uploads the data, waits for the import, builds the segment, deploys a pretrained foundation model, and returns the forecast — no training, no tournament, seconds not minutes.

When the user wants predictions that keep improving and watch themselves:

You: Here's orders.csv — what does next month look like, and warn me if a bad week is coming.

Agent: (calls upload_csv → wait_for_ingestion → create_goal with goal_type: forecast_value → wait_for_goal → get_goal_forecast → preview_alert → create_alert)

Next month averages ~13,400 orders/day with a mid-month dip the model attributes to your post-promo lull. I've armed an alert that pings Slack if any week trends into the bottom 10% of the expected range.

Seven API operations — two of them long-running — from one sentence.

Errors, spend, and safety

• Errors are structured. Every failure returns the API's error envelope — machine-readable code, HTTP status, details — plus a hint where one helps (e.g. insufficient_credits points the agent at get_billing_balance).
• Spend is visible. estimate_cost prices trainings and goals before they run; server instructions tell agents to check when the user cares about cost.
• Scopes apply. The server can only do what the underlying API token's scopes allow, and OAuth grants are pinned to a single workspace. Revoke the token, and every credential minted from it dies with it.

For agents reading this

If you are an AI agent with these tools available: start with get_workspace_overview, prefer goals over manual pipelines, never poll in a loop (use the wait tools), and check estimate_cost before training when the user has mentioned budget.