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. Because reads are always available, an agent can check what is already scheduled before proposing 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.

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.

The control that governs agent writes

Agent authoring is gated by its own switch at Settings ▸ Agent control planes ▸ Calendar control:

• 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.

This is separate 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. Read the Calendar guide for the ladder.

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 findings: failed, missed, overdue-waiting, and MISCONFIGURED (armed entries that can never succeed). Check this before assuming something did not 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
• missions — what mission-work entries act on
• cc-terminals — the workspace a workspace-mode entry opens