Temporal Cortex Scheduling

Calendar Scheduling & Booking

8 tools for calendar discovery, event querying, free slot finding, availability checking, RRULE expansion, and atomic booking. 7 read-only tools + 1 write tool (book_slot).

Runtime

These tools run inside the Temporal Cortex MCP server (@temporal-cortex/cortex-mcp@0.6.2), a compiled Rust binary distributed as an npm package.

Install and startup lifecycle:

1. npx resolves @temporal-cortex/cortex-mcp@0.6.2 from the npm registry (one-time, cached locally after first download)
2. The postinstall script downloads the platform-specific binary from the GitHub Release and verifies its SHA256 checksum against the embedded checksums.json — installation halts on mismatch
3. The MCP server starts as a local process communicating over stdio (no listening ports)
4. Calendar tools make authenticated API calls to your configured providers (Google Calendar API, Microsoft Graph API, CalDAV endpoints)

Credential storage: OAuth tokens are stored locally at ~/.config/temporal-cortex/credentials.json and read exclusively by the local MCP server process. No credential data is transmitted to Temporal Cortex servers. The binary's filesystem access is limited to ~/.config/temporal-cortex/ — verifiable by inspecting the open-source Rust code or running under Docker where the mount is the only writable path.

File access: The binary reads and writes only ~/.config/temporal-cortex/ (credentials and config). No other filesystem writes.

Network scope: Calendar tools connect only to your configured providers (googleapis.com, graph.microsoft.com, or your CalDAV server). No callbacks to Temporal Cortex servers. Telemetry is off by default.

Pre-run verification (recommended before first use):

1. Inspect the npm package without executing: npm pack @temporal-cortex/cortex-mcp@0.6.2 --dry-run
2. Verify checksums independently against the GitHub Release (see verification pipeline below)
3. For full containment, run in Docker instead of npx (see Docker containment below)

Verification pipeline: Checksums are published independently at each GitHub Release as SHA256SUMS.txt — verify the binary before first use:

# 1. Fetch checksums from GitHub (independent of the npm package)
curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.6.2/SHA256SUMS.txt

# 2. Compare against the npm-installed binary
shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp"

As defense-in-depth, the npm package also embeds checksums.json and the postinstall script compares SHA256 hashes during install — installation halts on mismatch (the binary is deleted, not executed). This automated check supplements, but does not replace, independent verification above.

Build provenance: Binaries are cross-compiled from auditable Rust source in GitHub Actions across 5 platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64). Source: github.com/temporal-cortex/mcp (MIT-licensed). The CI workflow, build artifacts, and release checksums are all publicly inspectable.

Docker containment (no Node.js on host, credential isolation via volume mount):

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "~/.config/temporal-cortex:/root/.config/temporal-cortex", "cortex-mcp"]
    }
  }
}

Build: docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git

Tools

Layer 0 — Discovery

Layer 2 — Calendar Operations

Layer 3 — Cross-Calendar Availability

Layer 4 — Booking

Critical Rules

1. Discover calendars first — call list_calendars when you don't know which calendars are connected. Use the returned provider-prefixed IDs for all subsequent calls.
2. Use provider-prefixed IDs for multi-calendar setups: "google/primary", "outlook/work", "caldav/personal". Bare IDs (e.g., "primary") route to the default provider.
3. TOON is the default format — output uses TOON (~40% fewer tokens than JSON). Pass format: "json" only if you need structured parsing.
4. Check before booking — always call check_availability before book_slot. Never skip the conflict check.
5. Content safety — event summaries and descriptions pass through a sanitization firewall before reaching the calendar API.
6. Timezone awareness — all tools accept RFC 3339 with timezone offsets. Never use bare dates.

Full Booking Workflow

1. Discover  →  list_calendars
2. Orient    →  get_temporal_context                      (temporal-cortex-datetime)
3. Resolve   →  resolve_datetime("next Tuesday at 2pm")  (temporal-cortex-datetime)
4. Check     →  check_availability(calendar_id, start, end)
5. Book      →  book_slot(calendar_id, start, end, summary)

If the slot is busy at step 4, use find_free_slots to suggest alternatives.

Two-Phase Commit Protocol

Agent calls book_slot(calendar_id, start, end, summary)
    │
    ├─ 1. LOCK    →  Acquire exclusive lock on the time slot
    │                 (in-memory local; Redis Redlock in Platform Mode)
    │
    ├─ 2. VERIFY  →  Check for overlapping events and active locks
    │
    ├─ 3. WRITE   →  Create event in calendar provider (Google/Outlook/CalDAV)
    │                 Record event in shadow calendar
    │
    └─ 4. RELEASE →  Release the exclusive lock

If any step fails, the lock is released and the booking is aborted. No partial writes.

Common Patterns

List Events This Week

1. list_calendars → discover connected calendars
2. get_temporal_context → current time (use temporal-cortex-datetime)
3. resolve_datetime("start of this week") → week start
4. resolve_datetime("end of this week") → week end
5. list_events(calendar_id: "google/primary", start, end)

Find Free Time Across Calendars

1. list_calendars → discover all connected calendars
2. get_availability(
     start, end,
     calendar_ids: ["google/primary", "outlook/work"],
     privacy: "full"
   ) → merged free/busy blocks with source_count

Check and Book a Slot

1. check_availability(calendar_id: "google/primary", start, end) → true/false
2. If free: book_slot(calendar_id: "google/primary", start, end, summary: "Team standup")
3. If busy: find_free_slots(calendar_id, start, end, min_duration_minutes: 30)

Expand Recurring Events

expand_rrule(
  rrule: "FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1",
  dtstart: "2026-01-01T10:00:00",     ← local datetime, no timezone suffix
  timezone: "America/New_York",
  count: 12
) → last Friday of every month for 2026

Provider-Prefixed Calendar IDs

All calendar IDs use provider-prefixed format:

Privacy Modes

Tool Annotations (book_slot)

Error Handling

Additional References

• Calendar Tools Reference — Complete input/output schemas for all 8 tools
• Multi-Calendar Guide — Provider routing, labels, privacy modes, cross-provider operations
• RRULE Guide — Recurrence rule patterns, DST edge cases, 5 LLM failure modes
• Booking Safety — 2PC details, concurrent booking, lock TTL, content sanitization