How does the scheduling layer 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 11 MCP tools organized in 4 layers: Layer 1 (Temporal Context) has 5 tools for time awareness and datetime resolution. Layer 2 (Calendar Ops) has 4 tools for 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_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: [{start: "09:00", end: "10:00"},
//   {start: "14:00", end: "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 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"
}
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
}
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":"09:00","end":"10:00"},
    {"start":"11:30","end":"12:30"},
    {"start":"14:00","end":"17:00"}
  ],
  "duration_minutes": 60,
  "calendars_checked": 2,
  "timezone": "America/Los_Angeles"
}
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
}

See all 11 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 get this wrong ~60% of the 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