MCP server

The Prolepsia MCP server lets AI assistants and agents use Prolepsia directly. Ask in plain words for a forecast, and the assistant writes the question, starts the forecast and reads the result for you. MCP (Model Context Protocol) is the open standard most AI tools use to call outside tools.

• Server address: https://app.prolepsia.com/api/v1/mcp/
• Transport: Streamable HTTP. Every request stands alone, so there is no session to keep.
• Tools: 153, listed at the end of this page.
• Logging in: browser assistants such as ChatGPT and Claude log in with your Prolepsia account (OAuth). Developer tools such as Claude Code, Cursor and Codex use an API key.

Both ways of connecting reach the same account, permissions, credits and limits as the API. Every tool calls the same code as the matching API call.

A forecast takes from about 5 minutes to about 1.5 hours, depending on its run mode. create_forecast returns a task id within a second, and the forecast keeps running on our servers. A well-behaved agent tells you the id straight away and checks back every few minutes. It never starts the same forecast twice because a result has not arrived yet. The agent skill teaches an agent exactly this.

Connect a browser assistant

ChatGPT, Claude.ai and Perplexity connect with OAuth, so you never paste a key into them.

1. In the assistant, add a custom connector (or search for Prolepsia in its connector directory).
2. Enter the server address: https://app.prolepsia.com/api/v1/mcp/
3. Log in to Prolepsia when asked, and approve the permissions.

The assistant then sees Prolepsia's tools. To remove its access, open Settings → API and AI clients in Prolepsia and choose Disconnect under Connected AI clients. That ends the connection at once.

Connect a developer tool

Create an API key first: Settings → API and AI clients → API keys → Create new key. Give it the forecasts:read and forecasts:write scopes, and questions:read and questions:write for the question tools. Then add Prolepsia to your tool. Replace pre_... with your key.

Claude Code

claude mcp add --transport http prolepsia https://app.prolepsia.com/api/v1/mcp/ \
  --header "Authorization: Bearer pre_..."

Restart Claude Code. The server shows as prolepsia under /mcp.

Cursor

Add this to ~/.cursor/mcp.json, then restart Cursor:

{
  "mcpServers": {
    "prolepsia": {
      "url": "https://app.prolepsia.com/api/v1/mcp/",
      "headers": { "Authorization": "Bearer pre_..." }
    }
  }
}

Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.prolepsia]
url = "https://app.prolepsia.com/api/v1/mcp/"

[mcp_servers.prolepsia.headers]
Authorization = "Bearer pre_..."

Claude Desktop

Claude Desktop reaches remote servers through mcp-remote, which needs Node.js. Add this to claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\):

{
  "mcpServers": {
    "prolepsia": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.prolepsia.com/api/v1/mcp/",
        "--header",
        "Authorization: Bearer pre_..."
      ]
    }
  }
}

Windsurf

Add this under mcpServers in ~/.codeium/windsurf/mcp_config.json, then restart the Cascade panel:

{
  "mcpServers": {
    "prolepsia": {
      "serverUrl": "https://app.prolepsia.com/api/v1/mcp/",
      "headers": { "Authorization": "Bearer pre_..." }
    }
  }
}

Any other client

Use the server address and send the key in an Authorization: Bearer pre_... header, or in X-Api-Key: pre_.... Check that the key works:

curl -sS -X POST https://app.prolepsia.com/api/v1/mcp/ \
  -H "Authorization: Bearer $PROLEPSIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The answer lists every tool.

Install the agent skill

The agent skill is a Markdown file that teaches an agent when to use Prolepsia, how to write a good question, how to wait for a forecast without starting it twice, and how to read the answer. The server works without it, but agents that have it make far fewer mistakes. The current version is 2026-10-24.2.

There are two forms of the same text:

Install the skill as a file of its own. Never write it over AGENTS.md or another file that holds your own instructions. The agent replaces an out-of-date copy only when the file holds nothing but the skill.

For Claude Code:

mkdir -p ~/.claude/skills/prolepsia && \
  curl -fsSL https://app.prolepsia.com/api/v1/mcp-skill/prolepsia.md -o ~/.claude/skills/prolepsia/SKILL.md

For Codex, from your project folder. Codex reads skills from .agents/skills, and each skill needs the header:

mkdir -p .agents/skills/prolepsia && \
  curl -fsSL https://app.prolepsia.com/api/v1/mcp-skill/prolepsia.md -o .agents/skills/prolepsia/SKILL.md

For Cursor, from your project folder. Cursor reads rules from .cursor/rules and needs a header on each one:

mkdir -p .cursor/rules && { \
  printf -- '---\ndescription: How to use the Prolepsia forecasting tools\nalwaysApply: false\n---\n'; \
  curl -fsSL https://app.prolepsia.com/api/v1/mcp-skill/agents.md; \
} > .cursor/rules/prolepsia.mdc

For Windsurf, from your project folder. Windsurf reads rules from .windsurf/rules:

mkdir -p .windsurf/rules && { \
  printf -- '---\ntrigger: model_decision\ndescription: How to use the Prolepsia forecasting tools\n---\n'; \
  curl -fsSL https://app.prolepsia.com/api/v1/mcp-skill/agents.md; \
} > .windsurf/rules/prolepsia.md

For any other agent, save agents.md as a file of its own in the folder where that agent reads rules.

Keep the skill up to date

An installed skill is a copy. It does not change when Prolepsia updates the skill, so Prolepsia tells your agent when its copy is old:

1. The skill file states its own version at the top: Skill version: 2026-10-24.2.
2. Every time an agent connects, the MCP server tells it the current version and where to download it.
3. When the two versions differ, the agent asks you to update. It updates the file itself only when the file holds nothing but the skill and it can write files.

https://app.prolepsia.com/api/v1/mcp-skill/version answers with the current version and both download addresses:

{
  "version": "2026-10-24.2",
  "skill_url": "https://app.prolepsia.com/api/v1/mcp-skill/prolepsia.md",
  "plain_url": "https://app.prolepsia.com/api/v1/mcp-skill/agents.md"
}

To update by hand, run the install command again. To update on a schedule, run this script from cron or your CI. It downloads the skill only when the version changed:

#!/bin/sh
# update-prolepsia-skill.sh: replace the installed skill when Prolepsia has a newer one.
# For Codex, use .agents/skills/prolepsia/SKILL.md in your project instead.
# Point this only at a file that holds the skill alone, never at AGENTS.md.
SKILL_FILE="$HOME/.claude/skills/prolepsia/SKILL.md"
INFO=$(curl -fsSL https://app.prolepsia.com/api/v1/mcp-skill/version) || exit 1
LATEST=$(printf '%s' "$INFO" | python3 -c 'import json, sys; print(json.load(sys.stdin)["version"])')
INSTALLED=$(sed -n 's/^Skill version: //p' "$SKILL_FILE" 2>/dev/null)
if [ "$LATEST" != "$INSTALLED" ]; then
  mkdir -p "$(dirname "$SKILL_FILE")"
  curl -fsSL https://app.prolepsia.com/api/v1/mcp-skill/prolepsia.md -o "$SKILL_FILE"
  echo "Updated the Prolepsia skill from ${INSTALLED:-nothing} to $LATEST."
fi

The script suits the Claude Code and Codex installs above, where the file is the skill alone. For Cursor and Windsurf, run the install command again. Never point the script at AGENTS.md or any file that holds more than the skill. Compare versions for equality only: a version is a date and a number, such as 2026-10-12.2.

How an agent should run a forecast

The skill teaches this flow. Follow it too if you write your own agent:

1. Write the question. normalize_question drafts a complete question from a rough idea. Show the user every field before anything runs, above all the resolution criteria.
2. Start it. create_forecast with the approved question, the run mode the user chose (runMode; list_run_modes gives each mode's time and price) and a fresh idempotencyKey. Tell the user the task id and the expected wait at once.
3. Watch it, briefly. wait_for_forecast waits up to 55 seconds and streams progress while it waits. It usually returns with waitTimedOut: true and the forecast still going. That is normal, not a failure.
4. Check back. Call get_forecast every few minutes until the status is completed, failed or cancelled. If the session ends, hand the user the task id; they can ask about it later.
5. Read it. On completed, give the number from forecast.forecastData, the medium report and the sources, next to the resolution criteria.

Never call create_forecast again because a result has not arrived: that starts a second paid forecast. Never cancel because a wait ended early. To retry a lost create_forecast call, send the same arguments with the same idempotencyKey.

Templates, presets and your own servers

The server can do what the Templates page and the Connections and Forecast presets tabs in Settings do:

• Question templates. list_question_templates lists the templates you can use. fill_question_template fills a template's blanks from a short request, such as "Nvidia, next quarter, revenue above $60 billion". create_question takes templateId and templateValues in its question, and the template writes the rest. save_question_as_template and create_question_template make new templates.
• Forecast presets. list_forecast_presets lists your presets and your organization's. create_forecast takes presetId to pick one for a forecast, or "none" for no preset, and connections with off and on lists to switch single connections for that forecast. set_forecast_preset_defaults sets your default.
• Your own servers. list_connections lists the MCP servers your forecasts can call and their tools. create_connection, update_connection and test_connection manage them, with the connections:read and connections:write permissions. A server that needs an OAuth sign-in gives a link through start_connection_sign_in, and a person opens it in a browser to finish.

Call the server from your own code

The server speaks JSON-RPC 2.0 over HTTP POST. Each request needs three headers: your key, Content-Type: application/json and Accept: application/json, text/event-stream. The answer is a short stream of server-sent events: progress notifications first when a tool sends them, then one data: line with the result.

These examples start a forecast and read its status. TypeScript uses the official SDK (npm install @modelcontextprotocol/sdk). Python uses plain HTTP with requests, which works whatever MCP library you have.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://app.prolepsia.com/api/v1/mcp/"),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.PROLEPSIA_API_KEY}` },
    },
  },
);
const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(`${tools.length} tools`);

const started = await client.callTool({
  name: "create_forecast",
  arguments: {
    question: {
      type: "binary",
      title: "Will Brent crude settle above $90 a barrel on 31 December 2026?",
      resolutionCriteria:
        "Resolves YES if the ICE Brent front-month settlement price on 31 December 2026 is above 90.00 USD.",
    },
    idempotencyKey: crypto.randomUUID(),
  },
});
const task = started.structuredContent as { id: string; status: string };
console.log(task.id, task.status); // "queued"

const latest = await client.callTool({
  name: "get_forecast",
  arguments: { taskId: task.id },
});
console.log((latest.structuredContent as { status: string }).status);
await client.close();

import json
import os
import uuid

import requests

MCP_URL = "https://app.prolepsia.com/api/v1/mcp/"
HEADERS = {
    "Authorization": f"Bearer {os.environ['PROLEPSIA_API_KEY']}",
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
}


def call_tool(name: str, arguments: dict) -> dict:
    """Call one MCP tool and return its structured result."""
    message = {
        "jsonrpc": "2.0",
        "id": str(uuid.uuid4()),
        "method": "tools/call",
        "params": {"name": name, "arguments": arguments},
    }
    response = requests.post(MCP_URL, headers=HEADERS, json=message, timeout=90)
    response.raise_for_status()
    # The answer is a server-sent event stream. Progress notifications come
    # first; the last "data:" line holds the result.
    reply = None
    for line in response.text.splitlines():
        if line.startswith("data: "):
            reply = json.loads(line[len("data: "):])
    if reply is None or "error" in reply:
        raise RuntimeError(f"MCP error: {reply}")
    result = reply["result"]
    if result.get("isError"):
        raise RuntimeError(result["content"][0]["text"])
    return result["structuredContent"]


task = call_tool(
    "create_forecast",
    {
        "question": {
            "type": "binary",
            "title": "Will Brent crude settle above $90 a barrel on 31 December 2026?",
            "resolutionCriteria": "Resolves YES if the ICE Brent front-month settlement price on 31 December 2026 is above 90.00 USD.",
        },
        "idempotencyKey": str(uuid.uuid4()),
    },
)
print(task["id"], task["status"])  # "queued"

latest = call_tool("get_forecast", {"taskId": task["id"]})
print(latest["status"])

curl -sS -X POST https://app.prolepsia.com/api/v1/mcp/ \
  -H "Authorization: Bearer $PROLEPSIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_forecast",
      "arguments": { "taskId": "2e1cc0b7-fa66-4ad4-a583-6da0e1f07ac7" }
    }
  }'

The curl answer looks like this. structuredContent holds the result as an object, and content[0].text holds the same result as JSON text for clients that read only text:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"id\":\"2e1cc0b7-...\",\"type\":\"forecast_task\",\"status\":\"completed\",...}"}],"structuredContent":{"id":"2e1cc0b7-...","type":"forecast_task","status":"completed","...":"..."},"isError":false}}

initialize is optional, because every request stands alone. A tool that refuses answers with isError: true and a text such as permission_denied: connection is missing required scope 'forecasts:write'. Add "_meta": {"progressToken": "any-id"} to params to get progress notifications from wait_for_forecast.

Permissions and limits

• A browser assistant asks you to approve scopes when it connects. An API key keeps the scopes it was created with. When a tool needs a scope the connection lacks, it answers permission_denied and names the scope.
• Only tool calls count against the rate limit. A browser assistant's connection may make 60 tool calls a minute. An API key shares its own per-minute limit (60 unless Prolepsia set another) with the API. Over the limit, a tool answers rate_limit_error and says how many seconds to wait.
• An assistant's OAuth access token lasts an hour, and the assistant renews it with a refresh token. Each refresh token works once; using an old one again ends the whole connection.
• Tools that start forecasts cost credits, like the API. get_credit_balance shows your balance, prices and plan.

Common errors

The Prolepsia Traces server

A second, read-only server at https://app.prolepsia.com/api/v1/mcp-traces/ reads the full trace of a forecast run: what the forecaster searched, what each research branch found and what it cost. It is open to Prolepsia admins and analysts only, needs the traces:read scope, and cannot start, change or cancel anything. Its skill is at https://app.prolepsia.com/api/v1/mcp-skill/prolepsia-traces.md.

Tool reference

Every tool of the server at https://app.prolepsia.com/api/v1/mcp/, by area. Your MCP client shows each tool's arguments; the agent skill lists them with their defaults.

Forecasts

Questions

Question context

Forecast chat

Schedules and automatic reruns

Sharing and notifications

Webhooks

Connections

Forecast presets

Question templates

Decisions

Account