Human Calendar Connections

Chronary can combine an agent’s own calendars with human calendars connected through Google or Microsoft OAuth. Humans stay in control of consent, calendar selection, agent mappings, and publishing. Agents receive only free/busy results and connection status—never OAuth tokens, account identities, calendar names, event titles, or event descriptions.

Two ways to start setup

From the console

Open Human calendars in the Chronary console and choose Google Calendar or Microsoft Outlook. Google connections are availability-only; Microsoft Outlook additionally offers availability plus publishing. After provider consent, choose which calendars may contribute busy time and map them to selected agents, all current agents, or all current and future agents.

From an agent

An agent can request setup without performing OAuth itself:

const link = await chronary.connectionLinks.create('cal_...', {
  capabilities: ['availability'],
});

// Deliver link.setup_url to a human, then poll without replaying the secret.
const status = await chronary.connectionLinks.get(link.id);

MCP agents use create_connection_link, get_connection_link, and cancel_connection_link. The setup_url is a short-lived bearer secret returned only by the original create call. If a create response says reused: true with setup_url: null, use the URL retained from the original call or cancel and create a replacement.

How availability is calculated

For each queried agent, Chronary combines:

busy intervals from all of the agent’s Chronary calendars;
recurring occurrences and availability rules;
imported iCal events, when configured; and
opaque busy intervals from every human calendar granted to that agent.

Availability responses include:

{
  "availability_state": "complete",
  "sources": {
    "chronary": "current",
    "external": "current",
    "last_synced_at": "2026-07-12T18:30:00.000Z"
  },
  "warnings": []
}

The default is fail-closed. If required human-calendar data is stale, partial, or unavailable, slots are empty and warnings contains availability_incomplete. REST, SDK, and CLI callers may pass allow_stale=true for non-committing exploration when a usable cached generation exists. MCP intentionally does not expose this override; agents should always inspect availability_state and warnings.

OAuth connections are refreshed into Chronary’s opaque busy cache rather than queried once per availability request. This protects provider APIs from high-TPS agent workloads and makes query latency predictable. Source timestamps and health make cache freshness explicit.

Agent mappings

Selected agents grants the chosen sources only to named agents.
All current agents snapshots the agents that exist when the mapping is created.
All current and future agents dynamically applies to every agent in the organization.

Connections are not visible organization-wide by default. Availability is included only when an active grant authorizes the queried agent. Agent-scoped API keys can create setup links only for their own agent’s calendars.

Optional event publishing (Microsoft Outlook)

Publishing is separate, opt-in, and available for Microsoft Outlook only. A human must grant publishing permission and select a writable Microsoft Outlook destination for each Chronary calendar. They can choose confirmed events only, or confirmed plus tentative events. Removing the destination stops future publishing; it does not move historical events.

A Microsoft availability-only connection can be reauthorized later with publishing permission. Google connections are availability-only. Agents cannot choose or inspect the human destination.

Managing a connection

The console shows provider, status, selected calendars, authentication time, and safe per-calendar sync health. A human can refresh, pause, resume, reauthorize, or disconnect a connection; enable, disable, or delete mappings; and replace or remove publishing destinations.

Google and Microsoft share the same availability behavior—the API, MCP tools, mappings, privacy boundary, and availability response are provider-neutral. Provider consent screens and supported account policies differ. Event publishing is the exception: it is available for Microsoft Outlook only, and Google connections are availability-only.

iCal fallback

iCal subscriptions remain useful for providers without OAuth support or when an organization cannot approve an OAuth app. They are read-only and polling-based. Prefer OAuth connections for Google and Microsoft because they provide explicit health, source selection, and controlled mappings (plus optional publishing for Microsoft Outlook).