# Temporal Cortex Mcp

> Calendar MCP server with atomic booking, conflict prevention, deterministic RRULE expansion, and TOON token compression for AI agents

- **Type:** MCP server
- **Install:** `agentstack add mcp-temporal-cortex-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [temporal-cortex](https://agentstack.voostack.com/s/temporal-cortex)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [temporal-cortex](https://github.com/temporal-cortex)
- **Source:** https://github.com/temporal-cortex/mcp
- **Website:** https://www.npmjs.com/package/@temporal-cortex/cortex-mcp

## Install

```sh
agentstack add mcp-temporal-cortex-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Temporal Cortex MCP

[](https://github.com/temporal-cortex/mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@temporal-cortex/cortex-mcp)
[](https://www.npmjs.com/package/@temporal-cortex/cortex-mcp)
[](https://smithery.ai/server/@temporal-cortex/cortex-mcp)
[](LICENSE)

**v0.9.1** · March 2026 · [Changelog](CHANGELOG.md) · **Website:** [temporal-cortex.com](https://temporal-cortex.com)

Give any AI agent autonomous scheduling capabilities. Temporal Cortex is open scheduling infrastructure that lets any AI agent schedule reliably — whether the other person has an AI agent or not, uses Google Calendar or Outlook, or responds instantly or days later. 18 tools across 5 layers handle contact resolution, temporal reasoning, cross-provider availability, and atomic booking. Accessible via MCP, A2A, REST, and browser. Powered by [Truth Engine](https://github.com/temporal-cortex/core). Install: `npx @temporal-cortex/cortex-mcp`.

## Two ways to use Temporal Cortex

### For individuals

Connect your calendars. Your AI agent handles the rest — checking availability, resolving time zones, and booking meetings without double-booking. Works with Claude Desktop, Cursor, OpenClaw, Manus, and any MCP-compatible AI client.

```bash
npx @temporal-cortex/cortex-mcp setup
```

The setup wizard walks you through provider authentication, timezone configuration, and MCP client setup interactively. You'll be scheduling in under a minute.

**Or use the managed Platform** — no Node.js required. Sign up at [app.temporal-cortex.com](https://app.temporal-cortex.com), connect your calendars via OAuth, and add a single MCP config with your API key.

### For developers

Add scheduling to your AI agent or product. 18 tools across 5 layers, 4 protocols (MCP, A2A, REST, Browser), atomic booking with Two-Phase Commit, and deterministic temporal computation powered by [Truth Engine](https://github.com/temporal-cortex/core).

- **Local MCP server:** `npx @temporal-cortex/cortex-mcp` — full tool suite, zero infrastructure
- **Platform REST API:** [app.temporal-cortex.com](https://app.temporal-cortex.com) — managed hosting, API keys, usage dashboard, Open Scheduling network
- **Framework integrations:** [LangGraph](docs/langgraph-integration.md), [CrewAI](docs/crewai-integration.md), [OpenAI Agents SDK](docs/openai-agents-integration.md)
- **REST API reference:** [temporal-cortex.com/docs/rest-api](https://temporal-cortex.com/docs/rest-api)

---

## Why do AI agents fail at calendar tasks?

Even the latest LLMs — GPT-5, Claude, Gemini — score below 50% on temporal reasoning tasks ([OOLONG benchmark](https://arxiv.org/abs/2511.02817)). Earlier models scored as low as 29% on scheduling and 13% on duration calculations ([Test of Time, ICLR 2025](https://arxiv.org/abs/2406.09170)). Ask "Schedule for next Tuesday at 2pm" and it picks the wrong Tuesday. Ask "Am I free at 3pm?" and it checks the wrong timezone. Then it double-books your calendar.

Most calendar tools for AI agents are thin CRUD wrappers that pass these failures through to a single calendar provider — no temporal awareness, no conflict detection, no safety net.

## What makes Temporal Cortex different?

- **Temporal awareness** — Agents call `get_temporal_context` to know the actual time and timezone. `resolve_datetime` turns `"next Tuesday at 2pm"` into a precise RFC 3339 timestamp. No hallucination.
- **Atomic booking** — Lock the time slot, verify no conflicts exist, then write. Two agents booking the same 2pm slot? Exactly one succeeds. The other gets a clear error. No double-bookings.
- **Computed availability** — Merges free/busy data across multiple calendars into a single unified view. The AI sees actual availability, not a raw dump of events to misinterpret.
- **Deterministic RRULE expansion** — Handles DST transitions, `BYSETPOS=-1` (last weekday of month), `EXDATE` with timezones, leap year recurrences, and `INTERVAL>1` with `BYDAY`. Powered by [Truth Engine](https://github.com/temporal-cortex/core), not LLM inference.
- **Token-efficient output** — TOON format compresses calendar data by ~40% fewer tokens than standard JSON, reducing costs and context window usage. TOON is the default output format for all data tools (`list_calendars`, `list_events`, `find_free_slots`, `expand_rrule`, `get_availability`). JSON is available via explicit `format: "json"`.

## What do I need to run Temporal Cortex?

- **Node.js 18+** (for `npx` to download and run the binary) or **Docker**
- **At least one calendar provider**:
  - **Google Calendar** — requires [Google OAuth credentials](docs/google-cloud-setup.md)
  - **Microsoft Outlook** — requires [Azure AD app registration](docs/outlook-setup.md) (`MICROSOFT_CLIENT_ID`)
  - **CalDAV** (iCloud, Fastmail, etc.) — requires an [app-specific password](docs/caldav-setup.md)

## How do I install Temporal Cortex?

**The fastest way to get started:**

```bash
npx @temporal-cortex/cortex-mcp setup
```

The `cortex-mcp setup` wizard walks you through provider authentication, timezone configuration, and MCP client setup interactively. See the [First Run Guide](docs/first-run-guide.md) for a detailed walkthrough.

**Or set up manually in 3 steps:**

1. **Install prerequisites** — Node.js 18+ (or Docker) and at least one calendar provider ([Google Calendar](docs/google-cloud-setup.md), [Microsoft Outlook](docs/outlook-setup.md), or [CalDAV](docs/caldav-setup.md)).
2. **Add the MCP configuration** to your AI client's config file (see client-specific examples below).
3. **Run the auth flow** — `npx @temporal-cortex/cortex-mcp auth google` (or `outlook` / `caldav`). This authenticates and configures timezone, week start, and telemetry preferences.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}
```

### Cursor

Add to Cursor's MCP settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}
```

### Windsurf

Add to Windsurf's MCP config (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}
```

### Docker

```bash
docker run --rm -i \
  -e GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
  -e GOOGLE_CLIENT_SECRET="your-client-secret" \
  -e TIMEZONE="America/New_York" \
  -v ~/.config/temporal-cortex:/root/.config/temporal-cortex \
  cortex-mcp
```

Build the image first: `docker build -t cortex-mcp .` (or build directly from the repo: `docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git`).

> **Need help with provider credentials?** See the setup guides: [Google Calendar](docs/google-cloud-setup.md), [Microsoft Outlook](docs/outlook-setup.md), [CalDAV (iCloud/Fastmail)](docs/caldav-setup.md). For a complete reference of all environment variables and configuration options, see the [Configuration Guide](docs/configuration-guide.md).

## How do I verify the installation?

SHA256 checksums are published with every [GitHub Release](https://github.com/temporal-cortex/mcp/releases) and embedded in the npm package as `checksums.json` for automatic postinstall verification. The postinstall script downloads the platform-specific binary and compares its SHA256 hash against the expected checksum in `checksums.json`. **On mismatch, installation fails with an error** — the binary is not installed and the error message includes both the expected and actual hashes.

**Verify manually:**

```bash
# Download the published checksums
curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt

# Compare against your installed binary
sha256sum "$(dirname "$(which cortex-mcp)")/../cortex-mcp" 2>/dev/null || \
  shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp" 2>/dev/null
```

**Build provenance:** Binaries are cross-compiled from Rust source in [GitHub Actions](https://github.com/temporal-cortex/mcp/actions) across 5 platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64). The computation layer is open source at [temporal-cortex/core](https://github.com/temporal-cortex/core).

**Docker containment:** For maximum isolation, run the MCP server in a container:

```bash
docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git
docker run --rm -i -v ~/.config/temporal-cortex:/root/.config/temporal-cortex cortex-mcp
```

No Node.js on the host, no direct filesystem access beyond the mounted config directory.

## How do I authenticate with calendar providers?

The easiest path is `npx @temporal-cortex/cortex-mcp setup`, which handles authentication, configuration, and MCP client setup in one guided flow. For individual provider auth, run the commands below:

```bash
# Google Calendar (default)
npx @temporal-cortex/cortex-mcp auth google

# Microsoft Outlook
npx @temporal-cortex/cortex-mcp auth outlook

# CalDAV (iCloud, Fastmail, or custom server)
npx @temporal-cortex/cortex-mcp auth caldav

# Docker (interactive auth — needs terminal + browser)
docker run --rm -it \
  -e GOOGLE_CLIENT_ID="your-id" -e GOOGLE_CLIENT_SECRET="your-secret" \
  -p 8085:8085 \
  -v ~/.config/temporal-cortex:/root/.config/temporal-cortex \
  cortex-mcp auth google
```

Each auth flow saves credentials to `~/.config/temporal-cortex/credentials.json` and registers the provider in `~/.config/temporal-cortex/config.json`. You can connect multiple providers — the server discovers all configured providers on startup and merges their calendars into a unified view.

During auth, the server guides you through interactive setup:
- **Timezone** — auto-detects your system timezone and opens a fuzzy-search picker with all 597 IANA timezones (type to filter, arrow keys to navigate)
- **Week start** — arrow-key selection between Monday (ISO standard) and Sunday
- **Telemetry** — optional anonymous usage data (default: off)

All preferences are stored in `~/.config/temporal-cortex/config.json` and used by all temporal tools. You can override them per-session with the `TIMEZONE` and `WEEK_START` env vars.

After authentication, verify it works by asking your AI assistant: *"What time is it?"* — the agent should call `get_temporal_context` and return your current local time.

For a guided workflow, install the [Temporal Cortex Agent Skills](https://github.com/temporal-cortex/skills) to teach your AI agent the orient-resolve-query-book pattern.

## Temporal Cortex Platform

Instead of running the MCP server locally via `npx`, you can use the managed Temporal Cortex Platform. No Node.js installation or local OAuth credentials required.

**Getting started:**

1. Sign up at [app.temporal-cortex.com](https://app.temporal-cortex.com).
2. Connect your Google Calendar or Microsoft Outlook account via OAuth in the dashboard.
3. Generate an API key from the dashboard.
4. Add the MCP config to your AI client (see examples below).

### Claude Desktop (Platform)

Add to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Cursor (Platform)

Add to Cursor's MCP settings (`~/.cursor/mcp.json`) using the same format:

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**Platform capabilities (beyond Local Mode):**

- **No OAuth credentials to manage** -- calendar connections are handled in the dashboard via standard OAuth flows.
- **No Node.js required** -- the client connects directly to the cloud endpoint over HTTP.
- **Usage dashboard** -- monitor tool calls, connected calendars, and billing from [app.temporal-cortex.com](https://app.temporal-cortex.com).
- **Managed calendar connections** -- token refresh, re-authentication, and provider health are handled server-side.
- **Multi-agent coordination** -- distributed locking prevents double-bookings when multiple agents schedule simultaneously.
- **Usage metering** -- track tool calls per agent and team from the dashboard.
- **Content firewall** -- automatic prompt injection detection and zero-width Unicode stripping.
- **Caller-based policies** -- enforce booking rules per agent (max duration, allowed hours, booking limits).

All 15 core tools and 5 layers work identically. The Platform adds safety, coordination, and visibility infrastructure on top, plus 3 additional Open Scheduling tools (see below).

### Open Scheduling + Temporal Links

Platform users can enable **Open Scheduling** to make their availability publicly queryable by AI agents and humans — no API key required.

1. Go to **Settings > Scheduling** in the dashboard.
2. Set a slug (e.g., `billy`) and enable Open Scheduling.
3. Share your **Temporal Link**: `book.temporal-cortex.com/billy`

**What callers get:**

- **Agent Card** (A2A discovery): `GET /public/{slug}/.well-known/agent-card.json`
- **Availability** (REST): `GET /public/{slug}/availability?date=2026-03-15`
- **Booking** (REST): `POST /public/{slug}/book`
- **A2A JSON-RPC**: `POST /public/{slug}/a2a` with `query_availability` or `book_slot` methods
- **Identity resolution**: `GET /resolve?identity=email@example.com` resolves to the user's Agent Card

**Human fallback:** The same Temporal Link works in a browser — humans see a booking page with date/time picker and form.

**Viral loop:** Every Agent Card exposes Temporal Cortex to the calling agent's framework. Every booking includes "Powered by Temporal Cortex" in the event description.

## What tools does Temporal Cortex provide?

Temporal Cortex exposes up to 18 Model Context Protocol tools organized in 5 layers. The 15 core tools are always available; 3 additional Open Scheduling tools are available in Platform Mode.

### Layer 0 — Discovery

| Tool | Description |
|------|-------------|
| `resolve_identity` | Resolves an identity (email, slug, or URL) to a Temporal Cortex user's Agent Card — returns slug, display name, and Open Scheduling status. Platform Mode only. |
| `search_contacts` | Searches the user's address book by name (Google People API, Microsoft Graph). Returns matching contacts with emails, phones, organization, and job title. Opt-in — requires contacts permission. |
| `resolve_contact` | Given a confirmed contact's email, determines the best scheduling path: Open Scheduling (instant booking), email, or phone. Chains with `resolve_identity` when Platform API is available. |

### Layer 1 — Temporal Context

| Tool | Description |
|------|-------------|
| `get_temporal_context` | Returns the current time, timezone, UTC offset, DST status, DST prediction (next transition date and direction), and day of week for the configured locale. Call this tool first in any calendar session. |
| `resolve_datetime` | Resolves human language expressions like "next Tuesday at 2pm" or "tomorrow morning" into precise RFC 3339 timestamps. |
| `convert_timezone` | Converts any RFC 3339 datetime from one IA

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [temporal-cortex](https://github.com/temporal-cortex)
- **Source:** [temporal-cortex/mcp](https://github.com/temporal-cortex/mcp)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@temporal-cortex/cortex-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-temporal-cortex-mcp
- Seller: https://agentstack.voostack.com/s/temporal-cortex
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.