Documentation

Everything you need to integrate Temporal Cortex into your AI agent workflow.

Quick Start

Get your AI agent scheduling meetings in under 2 minutes.

1

Install

Install the MCP server binary via npm. No signup required.

npx @temporal-cortex/cortex-mcp
2

Authenticate

Connect your calendar provider via OAuth.

npx @temporal-cortex/cortex-mcp auth google
3

Configure your AI agent

Add Temporal Cortex to your agent's MCP configuration. See agent configuration below for copy-pasteable JSON.

4

Start scheduling

Your agent now has access to 18 tools across 5 layers. See the tool reference for the full list.

Tool Reference

18 MCP tools organized in 5 layers. Each layer builds on the one below it.

Layer 0

Discovery

Contact search, identity resolution, and scheduling path discovery.

search_contacts Searches the user's contacts by name across Google People API and Microsoft Graph.
resolve_contact Resolves a contact's email to available scheduling paths (Open Scheduling, A2A, email, phone).
resolve_identity Resolves a person's name, email, or handle to their Temporal Cortex scheduling endpoint. Platform Mode only.
Layer 1

Temporal Context

Time awareness, datetime resolution, and computation. The foundation for all calendar operations.

get_temporal_context Returns current time, timezone, day of week, and week/month boundaries.
resolve_datetime Converts natural language expressions like "next Tuesday at 3pm" to ISO 8601 timestamps.
convert_timezone Converts a timestamp between IANA timezones.
compute_duration Calculates the duration between two timestamps in human-readable units.
adjust_timestamp Adds or subtracts time from a timestamp (e.g., "+2 hours", "-30 minutes").
Layer 2

Calendar Operations

Direct calendar data access, free slot computation, and recurrence rule expansion.

list_calendars Lists all connected calendars with their IDs, names, and provider types.
list_events Lists calendar events within a date range, expanding recurring events.
find_free_slots Finds available time slots on a given date within working hours.
check_availability Checks whether a specific time slot is free or busy on a calendar.
expand_rrule Expands an iCalendar RRULE into individual occurrence timestamps.
Layer 3

Availability

Cross-calendar availability merging into a unified free/busy view.

get_availability Merges availability across all connected calendar providers into a single free/busy timeline.
query_public_availability Queries another person's publicly shared availability via their Open Scheduling endpoint.
Layer 4

Booking

Atomic event creation with Two-Phase Commit, cross-user booking requests, and proposal composition.

book_slot Books a calendar event atomically — acquires lock, verifies no conflicts, writes event, releases lock.
request_booking Sends a booking request to another person's Open Scheduling endpoint. Recipient policies determine acceptance.
compose_proposal Composes a scheduling proposal message with proposed time slots for email, Slack, or SMS delivery.

Agent Configuration

Copy-paste the configuration for your AI agent or editor.

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"]
    }
  }
}

Zed

settings.json

{
  "context_servers": {
    "temporal-cortex": {
      "command": {
        "path": "npx",
        "args": ["@temporal-cortex/cortex-mcp"]
      }
    }
  }
}

Generic MCP

mcp.json

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["@temporal-cortex/cortex-mcp"],
      "transportType": "stdio"
    }
  }
}

Calendar Providers

Temporal Cortex connects to all major calendar providers. Manage multiple calendars from a single MCP server.

Google Calendar

OAuth 2.0 authentication. Personal and Google Workspace accounts.

Microsoft Outlook / Exchange

OAuth 2.0 via Microsoft Graph API. Personal and Microsoft 365 accounts.

CalDAV

Apple iCloud, Fastmail, Nextcloud, and any CalDAV-compatible server.

Resources

Source code, package registries, and community.

GH

temporal-cortex-mcp

Documentation, configs, and issue tracker

 GH

temporal-cortex-core

Rust core — TOON encoder + Truth Engine

 GH

temporal-cortex/skills

Agent Skills for the 4-step scheduling workflow

 npm

@temporal-cortex/cortex-mcp

MCP server binary on npm

 SM

Smithery

temporal-cortex/cortex-mcp on Smithery registry

 MCP

MCP Registry

Official MCP Registry listing

 GL

Glama

MCP server listing with quality scores

 CH

ClawHub

Agent Skills — datetime, scheduling, and router

Frequently asked questions

What format does Temporal Cortex output use?

All data tools return results in TOON (Token-Optimized Object Notation) by default, which reduces token count by ~40% compared to JSON. Every tool accepts a format parameter — set format: "json" to get standard JSON output instead. Layer 1 temporal tools return structured JSON regardless of the format setting.

What happens when book_slot encounters a conflict?

book_slot returns an error response with the conflicting event's details (summary, start time, end time). The lock is released and no event is created. The agent should call find_free_slots to suggest alternative times to the user.

Do I need OAuth for all tools?

No. Layer 1 tools (get_temporal_context, resolve_datetime, convert_timezone, compute_duration, adjust_timestamp) and expand_rrule work immediately with zero setup — no OAuth, no API keys, no network access. They perform pure local computation. Calendar-connected tools (Layers 2-4) require one-time OAuth consent.

Does Temporal Cortex work with Claude Desktop?

Yes. Add the MCP server to your claude_desktop_config.json with command: "npx" and args: ["@temporal-cortex/cortex-mcp"]. Restart Claude Desktop and you'll have access to all 18 tools. Copy-pasteable configuration is available on this page.