calendar-mcp

This server is the agent door to the Calendar — the platform's date-addressed scheduler. Its 14 tools cover the full surface you use in the view: list and read entries, create, update and delete them, inspect materialised occurrences, run one now, read overall status and health, and work with sketches.

It is a thin front over the scheduling engine in the routines daemon, so an agent and you are looking at exactly the same schedule — there is no separate agent-side copy to drift.

What agents actually do with it

Schedule their own follow-through. An agent that finishes an investigation and concludes the work needs a second pass next week can put that pass on the calendar itself, with the brief already written, rather than leaving it in a report you have to re-read and re-plan.

Plan around what exists. Reading the schedule stays available whenever authoring is switched off, so an agent checks what is already booked before it proposes anything — the same double-booking check the sketch flow performs.

Leave you a proposal instead of a decision. Any agent can write a sketch: freeform intent over marked areas of the week, which is inert until you dispatch it. This makes the calendar a proposal inbox for the whole fleet — an agent suggests a shape for your week, and nothing happens until you say so.

Sketches also carry a dry run that exists only here: with propose_only set, dispatching a sketch reports the entries it would create and creates none. There is no button for it in the view, so it is an agent-side capability rather than a shared one — and your own Configure via agent press always sends the flag off explicitly, so an agent's stored value can never decide what your press does.

Trigger something now. A scheduled occurrence can be run on demand, which is useful when an agent has just finished the prerequisite the entry was waiting for.

Two gates, and they answer different questions

Your subscription. The Calendar is part of Pro, and the gate covers every tool here — reads included. Without an active subscription each call answers with a plain "subscription required" result naming the tier it needs and where to upgrade; both paid tiers pass. This is the sharper of the two gates and the one to check first when everything on this page refuses. Tiers covers what each tier includes.

Calendar control, at Settings ▸ Terminals ▸ Agent control planes — a switch you hold, hot, no restart. Within a subscribed install:

• Writes refuse when it is off. Creating, editing or deleting entries and sketches is rejected.
• Reads keep answering. An agent can still see what is scheduled, so it plans correctly instead of guessing while blind.
• It never gates you. Your own edits in the view are unaffected, including edits to entries an agent created.
• Every agent write is recorded — entries carry their creator, and writes land in an audit log.

Note the shape: the subscription gate fails closed (in doubt, refuse), the control plane fails open (in doubt, allow), and only the second is yours to flip. Autonomy and controls covers why.

Both are separate again from the dispatch switch that governs whether anything fires at all. Authoring schedule and executing schedule are different questions and get different controls.

Autonomy travels on the entry

When an agent creates an agent-dispatched entry, the entry carries an autonomy level — report only, build, or full — exactly as it does when you create one by hand. The level constrains the agent that eventually runs, not the agent that scheduled it, and a new entry is stored at full unless it is lowered. The ladder and what each rung permits are on Autonomy and controls.

Tool	Parameters	What it does
calendar_list_events	include_archived: boolean	Every calendar entry (definitions, not firings). Use calendar_occurrences to see WHEN things run.
calendar_get_event	uuid*: string	One entry plus its recent run history — status, report path, brief path, errors. The first place to look when asking 'did that scheduled thing work?'.
calendar_create_event	—	Schedule something. A kind=agent_task with exec_mode=headless dispatches the schedule-executor at that moment, grounded and unattended — so write `instruction` for someone with no context but the brief. Returns the created entry including its uuid.
calendar_update_event	uuid*: string, **_EVENT_PROPS: object	Edit an entry. Changing the definition drops its not-yet-fired occurrences and rebuilds them from the new definition; run history is never touched.
calendar_delete_event	uuid*: string	Delete an entry and its occurrences, fired history included. To stop something firing while keeping the record, set status='paused' with calendar_update_event instead.
calendar_occurrences	from_utc*: string, to_utc*: string	Actual scheduled firings in a time window — what is on the calendar between two moments, with each one's status. This is the read for 'what is happening next week?'.
calendar_run_now	occurrence_uuid*: string	Fire one occurrence immediately. Goes through the same atomic claim as the clock, so a manual run and a scheduled firing can never both take it.
calendar_status	—	Whether dispatch is enabled, how many runs are in flight, concurrency cap, horizon — plus health. Counts: `failed` · `missed` · `overdue_waiting` (past their instant, includes the transient state every firing passes through) · `stuck_waiting` (past due AND actively deferred by the clock, i.e. genuinely stuck) · `misconfigured` (armed entries that can never succeed, or will do something other than what was configured) · `advisories` (configured-but-inert; never breaks a run). ★ `findings` and `advisory_findings` list the REASONS as {event_uuid, title, check, detail} — so you can go fix the specific entry rather than knowing only that a count is non-zero. Checks cover unparseable start times, incomplete scheduled emails, missing routines, broken mission links, a fleet pinned to one terminal while its mission has several open operations, and stored kind/mode combinations the coercion should have prevented. **Check this after authoring entries** — it is the surface that tells you whether what you armed can actually run. No args.
calendar_list_sketches	include_dismissed: boolean	Sketches — freeform intent written over time windows, which an agent turns into real entries. Includes their text, areas, status, and any entries they produced.
calendar_create_sketch	title*: string, text: string, areas: array, propose_only: boolean	Leave a sketch. This is how you PROPOSE scheduled work without scheduling it: write what should happen and when, and the operator either dispatches it for configuration or bins it. A sketch is inert by construction — it never fires, whatever it contains.
calendar_update_sketch	uuid*: string, title: string, text: string, areas: array, propose_only: boolean, status: string	Edit a sketch — its text, its areas, or its status (draft · dismissed).
calendar_delete_sketch	uuid*: string	Delete a sketch. Entries it already produced are left alone — they are real schedule now. Use calendar_undo_sketch to remove those.
calendar_dispatch_sketch	uuid*: string, propose_only: boolean	Hand a sketch to the schedule-executor in CONFIGURE mode: it reads the text, sees what is already booked near those windows, investigates as needed, and creates the entries. Returns immediately — the run takes minutes; poll calendar_list_sketches for the outcome.
calendar_undo_sketch	uuid*: string	Delete every entry a configure run produced and return the sketch to draft. The reversal half of dispatch — use it when a configuration came out wrong rather than deleting entries one by one.

Related

• Calendar — the view, the entry kinds, and the flows
• Autonomy and controls — the autonomy ladder, the control planes, and the dispatch switch
• missions — what mission-work entries act on
• cc-terminals — the workspace a workspace-mode entry opens