Developer docs

Kairotope plans a person's errands and commitments against real opening hours and live traffic, and remembers their places (home, their pharmacy, their kids' schools) and preferences. AI assistants reach it through an MCP server; other software can use the equivalent REST API. Both call the same planning engine.

• Connecting
• Authentication
• Tools
• Responses
• Example
• Guidance for assistants
• Plans, limits and coverage
• REST API
• Data handling

Connecting

Authentication

Every call is tied to one person's account (their household's saved places, preferences and plans) by a token. There are two ways to get one, and both reach the same account.

Sign in with Kairotope (OAuth 2.1)

For assistants that connect by OAuth, such as Meta Muse, ChatGPT and Claude. Point the assistant at https://kairotope.com/mcp; it discovers everything else from the first 401.

The person signs in with their email and presses Allow. The connection appears in their account under Assistants, where they can disconnect it, which also ends its refresh token.

Connector token

For assistants that take a pasted credential, such as Meta Muse, and for the REST API.

1. The person signs in at kairotope.com with their email (a one-time link; no password). The same link creates a free account.
2. In their account, under Assistants, they create a token. It starts with kt_ and is shown once. Kairotope stores only a hash of it.
3. They give it to their assistant through its secure credential prompt. The assistant sends it as a bearer token.

Connector tokens don't expire, and can be revoked at any time in the account, under Assistants. On /mcp, a missing, invalid, expired or revoked token gets HTTP 401 with WWW-Authenticate: Bearer resource_metadata="https://kairotope.com/.well-known/oauth-protected-resource/mcp", scope="kairotope", which is where OAuth clients start.

Tools

Every tool returns the response envelope as structuredContent, with its message also as text content.

Responses

Every tool answers with the same envelope. kind says what happened:

Other envelope fields: localNow and today (the household's current local time and date, on every result), plans (from list_plans), message (a short summary that's safe to relay as is), suggestions (places worth saving, each with a question to ask), reused (true when an identical request made moments earlier was answered from the stored plan), mapUrl (on plans, confirm_plan, check_plan and each of list_plans's plans, when plan pages are on for the account: a private link to the plan on a map, with each stop's times and directions; give it to the user as is; it works without signing in until 12 hours after the plan's last stop, and is also in message), and nextStep (an instruction for the assistant, not to read out: on plans, offer to lock the plan in and call confirm_plan if the user agrees). Over MCP, nextStep also arrives as a second text block.

Notices. Assistants can't receive a push from a connector, so Kairotope emails traffic alerts on the day of a plan, and any result may also carry notices: things the user should hear before your answer. A traffic_alert notice is an alert Kairotope emailed (with sentAt) that the user hasn't yet seen through an assistant, while its drive is still to come. A checkin notice asks how a finished day went, for up to 3 days after it: ask the user, then call report_outcome with its planId. Each notice has a message to relay and a nextStep for you, and comes once per account, on whichever assistant calls first. Results with kind error, not_found, limit or probe carry none. Over MCP, notices arrive as the first text block.

The plan object

Example

Request (MCP tools/call):

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "plan_errands",
    "arguments": {
      "intention": "Pick up my prescription, get groceries and be at dinner at The Oasis by 7",
      "date": "2026-10-03"
    }
  }
}

Result (structuredContent, abridged):

{
  "kind": "plan",
  "planId": "3f6c…",
  "message": "Leave at 5:12 PM. Walgreens first, since it closes at 6:00 PM… Say “confirm” to lock this plan in, and I'll check in that evening to see how it went.",
  "plan": {
    "planId": "3f6c…",
    "status": "on_track",
    "leaveBy": "2026-10-03T17:12:00-05:00",
    "stops": [
      { "seq": 1, "label": "Pick up prescription", "placeName": "Walgreens",
        "arriveAt": "2026-10-03T17:21:00-05:00", "departAt": "2026-10-03T17:31:00-05:00",
        "legMinutes": 9, "isFixed": false, "note": "Pharmacy closes at 6:00 PM." },
      { "seq": 2, "label": "Get groceries", "placeName": "H-E-B",
        "arriveAt": "2026-10-03T17:39:00-05:00", "departAt": "2026-10-03T18:09:00-05:00",
        "legMinutes": 8, "isFixed": false },
      { "seq": 3, "label": "Dinner", "placeName": "The Oasis",
        "arriveAt": "2026-10-03T18:50:00-05:00", "departAt": "2026-10-03T20:20:00-05:00",
        "legMinutes": 31, "isFixed": true }
    ],
    "totalDriveMinutes": 48,
    "minutesSavedVsNaive": 6,
    "unscheduled": [],
    "warnings": ["I assumed your prescription is at Walgreens (1505 W Whitestone Blvd)."],
    "explanation": "Leave at 5:12 PM. Walgreens first, since it closes at 6:00 PM…"
  },
  "suggestions": [
    { "label": "my pharmacy", "where": "Walgreens, 1505 W Whitestone Blvd", "kind": "pharmacy",
      "question": "Is the Walgreens on W Whitestone Blvd your usual pharmacy?" }
  ]
}

Guidance for assistants

The server sends these rules in its instructions. They're what makes plans correct across conversations:

1. Call plan_errands once per request. For changes, use revise_plan rather than re-sending the request.
2. When the user says where they live, or which pharmacy, store or school they use, call remember. Don't keep it only in your own memory or paste addresses into requests.
3. If a result has suggestions, ask each question, and call remember only when the user says yes.
4. Relay times, stop order, warnings and unscheduled exactly as returned. Don't recompute or round them.
5. Plans are drafts until confirmed. After presenting one, ask the user explicitly whether to lock it in, and call confirm_plan (no arguments needed) only on an explicit yes.
6. To drop a plan, call cancel_plan.
7. If a result's kind is error or not_found, it did not happen: tell the user, never say it worked.
8. Use ping for connectivity checks, never plan_errands.
9. If a result's kind is limit, relay its message and don't retry.
10. For "what are my plans?", call list_plans and answer from it: it knows which plans are confirmed and which are only drafts.
11. Use localNow (every result has it) for "today", "tomorrow" and how far away things are.
12. If a result has notices, pass them on before your answer: alerts with their times exactly as written; for a check-in, ask how the day went and call report_outcome.
13. To see whether a plan still holds, including from a check you schedule yourself, call check_plan, never plan_errands or revise_plan. From a scheduled check, message the user only when it returns an alert.

Plans, limits and coverage

Every new account starts with a free trial of the full product. Each plan and each revision counts toward a household's allowance. Repeated identical requests, connectivity checks and ping don't.

Prices and what each tier includes are on the pricing page. When an allowance runs out, calls return kind: "limit" with a message to relay, saying when more plans are available. Plans made on Free say in their message and warnings that they use typical traffic. get_household includes the household's tier (in plan) and what's left of its allowance.

• An identical request with unchanged saved places within 10 minutes returns the stored plan (reused: true) and doesn't count.
• At times of very high demand, trial and free requests may be asked to try again later.
• Plans typically take a few seconds; complex days with many stops can take longer.
• Coverage: United States. Kairotope is being tested in Central Texas first.
• Driving only, for now. Times are in the household's time zone, set from the browser at sign-up and from the saved home address (saving a home in another zone switches it, and the result's message says so).

REST API

The same operations are available over HTTPS at https://kairotope.com/api/v1 with the same bearer token, for software that doesn't speak MCP. The OpenAPI 3.1 description is at /api/v1/openapi.json.

Data handling

• Saved addresses and locations are encrypted at rest. Tokens are stored only as hashes.
• People can see, download and delete everything Kairotope holds in their account.
• Map data from third parties is kept no longer than their terms allow; after 30 days stored plans keep only times and labels.
• Full details: Privacy Policy and Terms.

Questions or problems: hello@kairotope.com