KASPR Predict MCP

KASPR Predict MCP is a timing planner for work that depends on the network. It is served as two Model Context Protocol servers over streamable HTTP, behind one bearer key. Any MCP client that can send an Authorization header can use them: Claude Code, Cursor, and Claude Desktop through the mcp-remote bridge.

The timing server (kaspr-timing) answers one question for calls, live streams, big uploads, agent batches and fixed live events: given a task at a proposed time and place, is there a materially better time? It answers in fixed wording, in every participant’s local time, and says nothing when nothing is better. It never blocks the time you proposed.

The scheduling server (kaspr-predict) ranks the hours between now and a deadline for batch jobs, agent loops and transfers: run now with timeout, retry and cache tuning for the hour, wait, or no good window. It can hold a chosen window and re-score it until it starts.

Both read the same model: KASPR’s typical week for every country, region and district, 168 hourly values of how usually rough the connection is, from a frozen data vintage named in every answer. Neither is a live measurement of the network.

claude mcp add --transport http kaspr-timing https://mcp.kasprdata.com/timing/mcp --header "Authorization: Bearer <your key>"
claude mcp add --transport http kaspr-predict https://mcp.kasprdata.com/mcp --header "Authorization: Bearer <your key>"

{
  "mcpServers": {
    "kaspr-timing": {
      "url": "https://mcp.kasprdata.com/timing/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    },
    "kaspr-predict": {
      "url": "https://mcp.kasprdata.com/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

{
  "mcpServers": {
    "kaspr-timing": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.kasprdata.com/timing/mcp", "--header", "Authorization: Bearer <your key>"]
    }
  }
}

The answer should name the hour in both places and either propose a steadier one or say nothing about timing. If you get a 401, the key is missing or has been revoked; if a tool is missing from the list, the client has not reloaded the server.

Every request to /timing/mcp, /mcp, /verdict and /verdict/best_window must carry Authorization: Bearer <key>. A missing or revoked key answers HTTP 401 with a JSON body whose error code is unauthorized; nothing else is returned.

Keys are tied to a tier (free, developer, team) that sets the scheduling server’s monthly credits and request rate. The timing server is not metered during the beta. Keys are personal: do not share them or embed them in client-side code. Tell us at once if a key may have leaked, and we rotate it.

Only bearer keys are supported today. Clients that require OAuth for remote servers, such as the connector screens in ChatGPT and claude.ai, cannot add these servers yet; that is planned.

Over stdio, for the local server, the key comes from the KASPR_MCP_KEY environment variable instead of a header.

Three read-only tools. Descriptions are the server’s own; the client sees them verbatim. Every call returns a verdict object (next section) in structuredContent and the same JSON as text, and every outcome is a verdict, never an exception: a bad request is invalid_request, a cap is rate_limited, a backend failure is a silent no_recommendation.

Every hour of a place’s typical week is one of three bands, from the chance that the hour is rough relative to that place’s own week. For two endpoints the hour is judged by the worse side, and that side is named. A suggestion needs an alternative that is at least one band steadier and materially so, inside the window and inside the local hours allowed at every endpoint; the nearest such hour wins, earlier before later. Otherwise the verdict is silent. A fixed event is never moved: it gets advice when its hour is usually congested, nothing otherwise.

Confidence comes from how much measurement backs the place: high or medium are usable; a place with low confidence falls back to its region, then its country, and if none qualifies the verdict is insufficient_data. Every verdict carries data_vintage, the date of the model data behind it.

The sentences are fixed. A client shows text verbatim when it is present and says nothing about timing when it is absent; explanation is kept for when the user asks why. The same words come back from any client and from the HTTP routes.

Verdict values

Bands and confidence

The sentences

Examples of the fixed wording, with places and times filled in by the server:

• — Call: “9 PM Nairobi (5 AM Melbourne (Tue)) is usually a congested hour on Nairobi networks; 7 PM Nairobi (3 AM Melbourne (Tue)) is typically steadier for a video call. Propose 7 PM Nairobi instead, or keep 9 PM Nairobi?”
• — Upload: “3 PM Vienna is usually a congested hour on your network. If it’s not urgent, starting at 6 PM Vienna should be noticeably faster. Continue now or schedule for 6 PM Vienna?”
• — Live stream: “3 PM Vienna is usually a congested hour on your network for live streaming. 6 PM Vienna is typically steadier. Keep 3 PM Vienna, or move it?”
• — Agent batch: “Deferring to 6 PM Vienna: current window congested, alternative mixed, confidence high.”
• — Fixed event: “It’s a fixed time so there’s nothing to change, but 2 PM Vienna is usually a congested hour on your network. If you can, use a wired connection and close cloud backups beforehand.”
• — Too little data: “I don’t have enough measurements for Norfolk Island to say anything reliable about 10 AM Melbourne, so I’d book it as planned.”

Reason codes

Five tools for work with a deadline. Credits meter the forecast and scheduling calls; classification is free, and run now answers are free. Every error carries recommendation run_now with fallback true, so an agent is never left without an answer.

Resources on the scheduling server: kaspr://taxonomy (task kinds and their defaults), kaspr://coverage (places covered, by level), kaspr://calibration (the decision parameters and whether they are calibrated), kaspr://changelog. Prompt: schedule_task(task), which walks an agent through exposure_class and best_window.

The timing verdicts are also plain HTTP, for scripts, pipelines and cross-checks: POST /verdict for check_timing and POST /verdict/best_window for best_window, with the same bearer key, a JSON body in the shape of the tool parameters, and the verdict object as the response. Every verdict is HTTP 200, including invalid_request and rate_limited; only a missing key is 401.

{
  "task_class": "live_call",
  "locations": [{ "label": "me", "query": "Melbourne" }, { "label": "Tim", "query": "Nairobi" }],
  "candidate_time": "2026-10-06T21:00:00+03:00",
  "feasibility": { "local_hours": [0, 24] },
  "user_timezone": "Australia/Melbourne"
}

{
  "spec_version": "0.3",
  "verdict": "suggest_alternative",
  "data_vintage": "2026-07-16",
  "candidate": { "time_local": [{ "label": "Tim", "time": "2026-10-06T21:00+03:00", "tz": "Africa/Nairobi" }, { "label": "me", "time": "2026-10-07T05:00+11:00", "tz": "Australia/Melbourne" }], "band": "congested", "confidence": "high", "source": "typical_week" },
  "alternative": { "time_local": [ … ], "band": "mixed", "confidence": "high", "source": "typical_week", "limiting_endpoint": "Tim" },
  "reason_code": "endpoint_congested_hour",
  "evidence_level": 1,
  "text": "9 PM Nairobi (5 AM Melbourne (Wed)) is usually a congested hour on Nairobi networks; 7 PM Nairobi (3 AM Melbourne (Wed)) is typically steadier for a video call. Propose 7 PM Nairobi instead, or keep 9 PM Nairobi?",
  "explanation": "Based on KASPR's typical weekly pattern for Nairobi networks (data up to July 2026), not a live forecast. …",
  "usage": { "tier": "beta", "verdicts_today": 1, "cap": null }
}

curl -s -X POST https://mcp.kasprdata.com/verdict \
  -H "Authorization: Bearer $KASPR_MCP_KEY" -H "content-type: application/json" \
  -d '{"task_class":"live_call","locations":[{"label":"me","query":"Melbourne"},{"label":"Tim","query":"Nairobi"}],"candidate_time":"2026-10-06T21:00:00+03:00","feasibility":{"local_hours":[0,24]},"user_timezone":"Australia/Melbourne"}'

• — Timing server: no daily or per-minute caps during the beta. A key that touches more than 15 distinct places in an hour is answered rate_limited until the hour passes, as a guard against enumeration.
• — Timing requests: at most 2 locations (exactly 1 for broadcast, upload_transfer and agent_batch); a window of at most 12 hours; a candidate no earlier than one hour ago; no upper limit on how far ahead.
• — Scheduling server: credits per month by tier (free 500, developer 20,000, team 250,000) and requests per minute (10, 60, 300); free keys can forecast up to 24 hours ahead for up to 2 places; best_window takes up to 5, 10 or 20 places by tier; deadlines up to 30 days ahead; holds up to 720 hours, at most 20 active per key. The whole-week route used by the client library needs a developer or team key.
• — Place queries: a plain name (“Nairobi”, “Vienna”), “City, CC” or “City, Country” (“Nairobi, KE”), a district with its city and country (“Prahran, Melbourne, AU”), or coordinates; at most four comma-separated parts, ≤ 80 characters. Five micro-territories are not covered.
• — Requests per key: the key’s per-minute limit (10 for free keys) applies to the timing tools as well and comes back as a rate_limited verdict; request bodies are capped (64 KB on the routes); at most 20 active holds per key.
• — Distinct places per day: a key may touch 50 (free), 500 (developer) or 5,000 (team) different places per UTC day across every tool; places already looked up that day cost nothing. Over the allowance, the scheduling decision and its tuning still come but without per-place numbers, raw forecasts are refused, and the timing tools answer rate_limited with “You’ve checked a lot of different places today, so I’d go ahead as planned.”

The timing server never raises: every outcome is a verdict object over HTTP 200, and a client shows text when it is present and otherwise says nothing. The scheduling server answers structured errors with recommendation run_now and fallback true, so an agent can always carry on.

• — The hosted servers never measure you. They answer from the model and your request alone. The timing server returns no numbers: bands, times and a sentence.
• — The model is KASPR’s typical week for each place, from a frozen data vintage named in every answer. Verdicts say so in their own words (“usually”, “typically”, “not a live forecast”).
• — We log each call: the key, the tool, the task class, the verdict, its confidence and source, the number of places, and timing. Place names and coordinates you send are resolved and are not kept beyond the request log needed to operate the service and enforce the terms.
• — In the on-device mode of the scheduling server, the rolling series of your own latency measurements lives in one file on your machine, readable only by you; the only call to KASPR is a forecast by place id. Outcome reports are opt-in and carry job metrics only.

Use of the MCP servers, the HTTP routes and everything they return is governed by the KASPR Schedule terms and conditions, including the additional terms for the KASPR Predict MCP. A key is issued to someone who has accepted them, and using a key, directly or through an agent you configure, is acceptance of them. In short: the outputs are statistical tendencies from past measurement, not live conditions, not advice, and not a promise that any hour will be better than another; you and your agents decide what to do with them, at your own risk.

Read the terms and conditions