How does the scheduling infrastructure work?

Temporal Cortex is a Model Context Protocol (MCP) server that gives AI agents deterministic calendar capabilities — temporal context, datetime resolution, multi-calendar availability merging, and conflict-free booking with Two-Phase Commit.

What is the 4-layer tool architecture?

Temporal Cortex provides 12 MCP tools organized in 4 layers: Layer 1 (Temporal Context) has 5 tools for time awareness and datetime resolution. Layer 2 (Calendar Ops) has 5 tools for calendar listing, events, free slots, availability, and RRULE expansion. Layer 3 (Availability) merges free/busy data across all providers. Layer 4 (Booking) provides atomic booking with Two-Phase Commit.

Layer 4

Booking

Safe mutation with Two-Phase Commit

book_slot
Layer 3

Availability

Cross-calendar merge into unified free/busy view

get_availability
Layer 2

Calendar Operations

Direct calendar data access and computation

list_calendars list_events find_free_slots check_availability expand_rrule
Layer 1

Temporal Context

Time awareness, resolution, and computation

get_temporal_context resolve_datetime convert_timezone compute_duration adjust_timestamp

How does a typical agent workflow look?

When an agent needs to schedule a meeting, it follows this 4-step pattern:

1

Orient — get_temporal_context

Agent learns what "now" means — current time, timezone, day of week, week boundaries. This grounds all subsequent time reasoning.

get_temporal_context()
// Returns: current_time, timezone, day_of_week,
//   week_start, week_end, month boundaries
2

Resolve — resolve_datetime

Natural language like "next Tuesday at 3pm" becomes an exact ISO 8601 timestamp. Deterministic — same input always produces same output.

resolve_datetime({
  expression: "next Tuesday at 3pm"
})
// Returns: "2026-03-03T15:00:00-08:00"
3

Query — find_free_slots

Checks availability across all connected calendars. Returns actual free time slots — not raw events for the agent to figure out.

find_free_slots({
  date: "2026-03-03",
  duration_minutes: 60,
  start_hour: 9,
  end_hour: 17
})
// Returns TOON: slots [09:00–10:00, 14:00–17:00]
4

Book — book_slot

Atomic booking with Two-Phase Commit: lock the slot, verify no conflicts, write the event, release the lock. If any step fails, everything rolls back.

book_slot({
  calendar_id: "primary",
  title: "Team Sync",
  start: "2026-03-03T14:00:00",
  end: "2026-03-03T15:00:00"
})
// Lock acquired → conflict check ✓ → booked ✓

What do the tool responses look like?

Every Temporal Cortex tool returns structured data in TOON (Token-Optimized Object Notation) by default — a format designed for LLM consumption that reduces calendar data by ~40% compared to raw JSON. Here are real request/response examples for the 4 most-used tools — one from each layer.

Layer 1

get_temporal_context

Returns the agent's current temporal context — time, timezone, week boundaries, and day metadata. No parameters required.

Request

{
  "tool": "get_temporal_context",
  "arguments": {}
}

Response

current_time: "2026-02-25T14:30:00-08:00"
timezone: America/Los_Angeles
utc_offset: "-08:00"
day_of_week: Wednesday
week_start: "2026-02-23T00:00:00-08:00"
week_end: "2026-03-01T23:59:59-08:00"
month_start: 2026-02-01
month_end: 2026-02-28
TOON
239 chars
JSON
290 chars
18% smaller with TOON
Layer 1

resolve_datetime

Converts natural language to an exact ISO 8601 timestamp. Deterministic — same input always produces the same output.

Request

{
  "tool": "resolve_datetime",
  "arguments": {
    "expression": "next Tuesday at 3pm"
  }
}

Response

resolved: "2026-03-03T15:00:00-08:00"
timezone: America/Los_Angeles
input: next Tuesday at 3pm
day_of_week: Tuesday
is_ambiguous: false
TOON
135 chars
JSON
169 chars
20% smaller with TOON
Layer 2

find_free_slots

Returns actual free time slots across all connected calendars — not raw events for the agent to interpret.

Request

{
  "tool": "find_free_slots",
  "arguments": {
    "date": "2026-03-03",
    "duration_minutes": 60,
    "start_hour": 9,
    "end_hour": 17
  }
}

Response

date: 2026-03-03
slots
  start      end
  "09:00"    "10:00"
  "11:30"    "12:30"
  "14:00"    "17:00"
duration_minutes: 60
calendars_checked: 2
timezone: America/Los_Angeles
TOON
174 chars
JSON
258 chars
33% smaller with TOON
Layer 4

book_slot

Atomically books a calendar event with Two-Phase Commit — lock, verify, write, release. If any step fails, everything rolls back.

Request

{
  "tool": "book_slot",
  "arguments": {
    "calendar_id": "google/primary",
    "title": "Team Sync",
    "start": "2026-03-03T14:00:00",
    "end": "2026-03-03T15:00:00",
    "description": "Weekly standup"
  }
}

Response

status: booked
event_id: ev_a1b2c3d4e5f6
calendar_id: google/primary
title: Team Sync
start: "2026-03-03T14:00:00-08:00"
end: "2026-03-03T15:00:00-08:00"
lock_acquired: true
conflicts_found: 0
TOON
192 chars
JSON
243 chars
21% smaller with TOON

See all 12 tool signatures and parameters →

Why not just use Google Calendar API directly?

Google Calendar API is a CRUD interface — it reads and writes events. That's it. An AI agent using it directly faces these problems:

  • No atomic operations. Two agents can read "3pm is free" simultaneously and both book it. Google has no locking primitive.
  • No recurrence intelligence. Google returns RRULE strings like FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20261231. The LLM must expand this into individual occurrences, handling DST transitions, EXDATE exceptions, and BYSETPOS modifiers. LLMs score as low as 13% accuracy on duration calculations (Test of Time).
  • No cross-provider view. Google API only sees Google Calendar. If you have an Outlook work calendar and an iCloud personal calendar, the agent is blind to conflicts across them.
  • No availability computation. The API returns a list of events. Computing "when are you free?" requires merging events across calendars, respecting working hours, handling all-day events, and returning actual free slots. This is application logic, not API output.
  • No temporal reasoning. "Next Friday at 3pm" depends on timezone, locale, and the current date. Google's API expects ISO 8601 timestamps. The LLM must resolve the expression correctly before making the API call.

Temporal Cortex wraps these raw APIs in a safety layer — deterministic RRULE expansion via Truth Engine, cross-provider availability merging, and atomic booking with Two-Phase Commit. The agent gets reliable answers instead of raw data it must interpret.

Quick start: add to your AI agent

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["@temporal-cortex/cortex-mcp"]
    }
  }
}

VS Code / Cursor / Windsurf

// .vscode/mcp.json
{
  "servers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["@temporal-cortex/cortex-mcp"]
    }
  }
}

See configs for Zed, Windsurf, and more →

Compare to alternatives View pricing Full documentation Enterprise