Chronary

ai.chronaryPublished by chronary.aiOfficial publisherv1.5.2Updated Oct 24, 2026

Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

Chronary is a calendar API for AI agents that lets an assistant manage agents, calendars, events, availability and scheduling proposals.

What you can do
Create and manage agents, calendars and their availability rules, including buffer times and working hours. Create, read, update, cancel, hold, confirm and release events, and check when one or several agents are free to find meeting times. Run scheduling proposals: send candidate slots to participants, collect accept, decline or counter responses, and resolve or cancel them. Link external iCal feeds such as Google Calendar or Outlook and trigger or inspect their sync. Manage agent-scoped API keys, webhook subscriptions and their deliveries, and read the audit log and usage.
When to use it
Use it when an assistant should book, reschedule or cancel appointments, answer what an agent is doing now, or coordinate a meeting across several agents and human calendars. It suits agent-driven scheduling workflows that need availability checks and proposal-based negotiation.
Requirements
A Chronary account and an API key (org-level or agent-scoped), supplied as the CHRONARY_API_KEY environment variable or as a bearer Authorization header. The local package runs with npx and needs Node.js 18 or later; a remote endpoint at api.chronary.ai is also available. Some proposal and key/webhook tools require an org-level key.
Before you install
The API key is a secret placed in client config; agent-scoped keys can only act for one agent, while org-level keys can create, revoke and delete keys, agents and webhooks. Many tools write, cancel or permanently delete data, including events, calendars, agents, webhook subscriptions and scoped keys; revocation and deletion cannot be undone. Creating a scoped key or webhook returns a plaintext secret or signing secret only once. Linked iCal feeds bring external calendar data into availability.

Installation

In SourceWeft

  1. Open Chronary in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/ai.chronary%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "chronary": {
      "type": "http",
      "url": "https://api.chronary.ai/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

@chronary/mcp

[Smithery]

MCP server for Chronary — calendar tools for AI assistants.

Drops 50 calendar tools (manage agents, calendars, and events, request human Google/Microsoft setup, find meeting times, run scheduling proposals, configure availability rules, manage webhooks, iCal subscriptions, scoped keys, audit log, and usage) into any MCP-compatible client: Claude Desktop, Cursor, VS Code Copilot, Claude Code, Windsurf.

One-click install via Smithery: npx -y @smithery/cli mcp add chronary/agent-calendar --client claude (swap --client for cursor, vscode, claude-code, windsurf, …).

Prerequisites

  1. A Chronary account — sign up at chronary.ai.
  2. An API key from the console (starts with chr_sk_).
  3. Node.js ≥ 18 on the machine where the MCP client runs.

Client configurations

All examples use npx -y @chronary/mcp, which downloads and runs the latest version on demand. No install step required.

Claude Desktop

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

macOS / Linux:

json
{  "mcpServers": {    "chronary": {      "command": "npx",      "args": ["-y", "@chronary/mcp"],      "env": {        "CHRONARY_API_KEY": "chr_sk_..."      }    }  }}

Windows (uses cmd /c because spawn can't resolve npx.cmd directly):

json
{  "mcpServers": {    "chronary": {      "command": "cmd",      "args": ["/c", "npx", "-y", "@chronary/mcp"],      "env": {        "CHRONARY_API_KEY": "chr_sk_..."      }    }  }}

Restart Claude Desktop after saving.

Cursor

Edit .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (user-level):

macOS / Linux:

json
{  "mcpServers": {    "chronary": {      "command": "npx",      "args": ["-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Windows:

json
{  "mcpServers": {    "chronary": {      "command": "cmd",      "args": ["/c", "npx", "-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

VS Code Copilot

Edit .vscode/mcp.json (workspace) or run the MCP: Open User Configuration command for a user-level config. VS Code uses a different top-level key (servers) and requires an explicit type:

macOS / Linux:

json
{  "servers": {    "chronary": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Windows:

json
{  "servers": {    "chronary": {      "type": "stdio",      "command": "cmd",      "args": ["/c", "npx", "-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Claude Code

Edit .mcp.json at the project root, or ~/.claude.json for user-level:

macOS / Linux:

json
{  "mcpServers": {    "chronary": {      "command": "npx",      "args": ["-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Windows:

json
{  "mcpServers": {    "chronary": {      "command": "cmd",      "args": ["/c", "npx", "-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows):

macOS / Linux:

json
{  "mcpServers": {    "chronary": {      "command": "npx",      "args": ["-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Windows:

json
{  "mcpServers": {    "chronary": {      "command": "cmd",      "args": ["/c", "npx", "-y", "@chronary/mcp"],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Windsurf limit: Cascade enforces a hard cap of 100 total tools across all MCP servers and 20 tool calls per prompt. Chronary exposes 50; consider --tools filtering if you stack multiple servers.

Reducing context with --tools

Exposing all 50 tools uses LLM tokens on every request. For focused workflows, whitelist only what you need:

json
{  "mcpServers": {    "chronary": {      "command": "npx",      "args": [        "-y", "@chronary/mcp",        "--tools", "list_events,find_meeting_time,create_event"      ],      "env": { "CHRONARY_API_KEY": "chr_sk_..." }    }  }}

Pointing at a non-production API

For self-hosted Chronary instances or development against a local API:

json
{  "args": ["-y", "@chronary/mcp", "--base-url", "http://localhost:8787"]}

Tools exposed

ToolRead-onlyDestructive
list_calendars, get_calendar✓
create_calendar, update_calendar
delete_calendar✓
list_events, get_event✓
create_event, update_event, confirm_event
cancel_event, release_event✓
list_agents, get_agent✓
create_agent, update_agent
delete_agent✓
get_availability, find_meeting_time✓
get_calendar_context✓
list_proposals, get_proposal✓
create_proposal, respond_to_proposal, resolve_proposal
cancel_proposal✓
get_availability_rules✓
set_availability_rules
clear_availability_rules✓
list_webhooks, get_webhook, list_webhook_deliveries✓
create_webhook, update_webhook
delete_webhook✓
list_ical_subscriptions, get_ical_subscription✓
subscribe_ical, update_ical_subscription, sync_ical_subscription
delete_ical_subscription✓
list_scoped_keys✓
create_scoped_key
revoke_scoped_key✓
get_audit_log✓
accept_terms
get_usage✓

Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are surfaced to MCP clients so hosts can decide whether to require user confirmation.

Troubleshooting

"spawn npx ENOENT" on Windows — use the cmd /c npx ... form shown above.

"CHRONARY_API_KEY is required" — the env block must be nested under the server entry, not at the top of the config file.

Tools aren't showing up — restart the MCP client after editing the config. Most clients only read the config on startup.

Verify the binary runs locally:

sh
CHRONARY_API_KEY=test npx -y @chronary/mcp --help

Links

License

Apache-2.0

Source: README.md at commit 8ac0cff

Tools

54

create_agent

Register your agent (AI assistant, human participant, or resource) with Chronary so it can own calendars, events, and webhooks.

Parametersnamerequiredtyperequireddescription

list_agents

List all agents in your organization

Parameterstypelimitoffsetstatus

create_calendar

Create a calendar to hold events and track availability. Calendars are required before creating events — call this first when setting up a new agent. An agent can have multiple calendars (e.g. "Work", "Personal"). Org-level calendars (no agent_id) can be used as shared resources like meeting rooms.

Parametersnamerequiredagent_idtimezonerequireddefault_reminders

create_event

Create a booking, appointment, meeting, hold, or any scheduled event on a calendar. The calendar_id comes from create_calendar or list_events. Once created, this event blocks the agent's availability during that time and appears in availability queries. Use status="hold" with hold_expires_at to tentatively reserve a slot that auto-releases on TTL.

Parameterstitlerequiredstatusall_dayend_timerequiredremindersstart_timerequiredcalendar_idrequireddescriptionhold_priorityhold_expires_atrecurrence_rule

list_events

List events on a calendar or across an agent's calendars, including internally created events and externally synced events from iCal subscriptions (e.g. Google Calendar, Outlook). Provide `calendar_id` OR `agent_id`. Narrow with `start_after`/`start_before` (time window), `status`, and `source`.

Parameterslimitexpandoffsetsourcestatusagent_idcalendar_idstart_afterstart_before

get_event

Retrieve a single event by ID, including its title, times, status, location, reminders, and metadata. Works for both internally created events and externally synced iCal events. `calendar_id` is optional — if omitted the calendar is resolved from the event. Provide `calendar_id` to fail fast on cross-calendar typos.

Parametersevent_idrequiredcalendar_id

update_event

Reschedule or edit an event — change its title, description, start/end times, location, status, reminders, or metadata. Use this to move an appointment to a new time or update its details. Provide only the fields you want to change. Holds cannot be edited via this tool (use confirm_event / release_event). External iCal events are read-only. `calendar_id` is optional — if omitted it is resolved from the event.

Parameterstitlestatusall_dayend_timeevent_idrequiredmetadataremindersstart_timecalendar_iddescriptionrecurrence_rule

get_availability

Check when a single agent is free across its Chronary calendars and any human calendars authorized for that agent. This tool is fail-closed: always inspect `availability_state` and `warnings` before using slots. Accepts `start`/`end` or the `start_time`/`end_time` aliases.

Parametersendstartagent_idrequireddurationend_timestart_timeinclude_busyslot_duration

find_meeting_time

Find slots when multiple agents are free across Chronary calendars and any human calendars authorized for each agent. This tool is fail-closed: always inspect `availability_state` and `warnings` before using slots. Accepts `agents`/`start`/`end` or their aliases.

Parametersendstartagentsdurationend_timeagent_idscalendarsstart_timeinclude_busyslot_duration

cancel_event

Delete or cancel an event from a calendar. Use this to remove, cancel, or delete any scheduled event or appointment. The event is marked cancelled and excluded from future availability calculations. For a recurring series, pass `occurrence_start` to cancel just that one occurrence (the series continues); omit it to cancel the whole series. `calendar_id` is optional — if omitted the calendar is looked up from the event. Provide `calendar_id` to fail fast on cross-calendar typos.

Parametersevent_idrequiredcalendar_idoccurrence_start

confirm_event

Promote a held event to a confirmed booking. The event must currently have status="hold" and its hold_expires_at must not have passed. After confirmation, event.started and event.ended lifecycle webhooks fire at the scheduled times.

Parametersevent_idrequired

release_event

Manually release a held event before its hold_expires_at. The event must currently have status="hold". Frees the slot for other agents to book.

Parametersevent_idrequired

subscribe_ical

Link an external iCal feed (e.g. a human's Google Calendar) to an agent's calendar so external events appear in availability calculations. The target calendar must be owned by the specified agent — create the calendar with that agent_id first (org-level calendars without an agent_id cannot host external iCal subscriptions; create a dedicated per-agent calendar for sync targets).

Parametersurlrequiredlabelagent_idrequiredcalendar_idrequired

list_ical_subscriptions

List an agent's external iCal feed subscriptions (e.g. linked Google Calendar / Outlook feeds), including their sync status and last sync time.

Parameterslimitoffsetstatusagent_idrequired

get_ical_subscription

Get a single external iCal feed subscription by id, including its sync status, last sync time, and last error.

Parameterssubscription_idrequired

update_ical_subscription

Update an external iCal feed subscription — change its label or its feed URL. Changing the URL forces a full re-sync on the next poll.

Parametersurllabelsubscription_idrequired

delete_ical_subscription

Delete an external iCal feed subscription. Events previously synced from the feed are no longer refreshed.

Parameterssubscription_idrequired

sync_ical_subscription

Trigger an immediate sync of an external iCal feed subscription instead of waiting for the next scheduled poll. Returns once the sync has been queued.

Parameterssubscription_idrequired

get_calendar_context

Get a calendar's temporal context in a single call: the current event (if one is happening now), the next upcoming event, recent past events, a short upcoming window, and the owning agent's status (idle/working/waiting/error). Use this to answer "what is this agent doing right now?" without issuing multiple list_events queries.

Parameterscalendar_idrequired

create_proposal

Create a scheduling proposal — send a set of candidate time slots to one or more participant agents so they can accept, decline, or counter-propose. The organizer agent owns the proposal; once every participant responds, the system auto-resolves to the highest-scoring slot (or cancels if all decline). Requires an org-level API key. Pro plan only.

Parametersslotsrequiredtitlerequiredexpires_atcalendar_idrequireddescriptionorganizer_agent_idrequiredparticipant_agent_idsrequired

list_proposals

List scheduling proposals for the org. Filter by status (pending|confirmed|expired|cancelled) or organizer_agent_id. Requires an org-level API key.

Parameterslimitoffsetstatusorganizer_agent_id

get_proposal

Get a scheduling proposal by id, including its slots and per-participant responses. Requires an org-level API key.

Parametersproposal_idrequired

respond_to_proposal

Submit a response (accept / decline / counter) on behalf of one participant agent to an open proposal. An "accept" requires the slot id from the proposal; a "counter" can suggest alternative slots. When all participants have responded the proposal auto-resolves — no separate resolve call needed in the normal flow. Requires an org-level API key. Pro plan only.

Parametersmessageagent_idrequiredresponserequiredproposal_idrequiredcounter_slotsselected_slot_id

resolve_proposal

Force-resolve an open proposal using responses collected so far. Picks the highest-scoring slot among those accepted by the most participants and creates a confirmed calendar event. If every response was "decline", the proposal is cancelled instead. Use when you want to close out a proposal without waiting for every participant. Requires an org-level API key. Pro plan only.

Parametersproposal_idrequired

cancel_proposal

Cancel an open proposal. Fires a proposal.cancelled webhook with reason="organizer_cancelled". Requires an org-level API key. Pro plan only.

Parametersproposal_idrequired

set_availability_rules

Set or replace the availability rules on a calendar — buffer times before/after events and optional per-day working hours. When these rules are set, every availability query on this calendar automatically applies them (busy-block expansion for buffers, masking outside working hours). Upsert: overwrites any existing rules.

Parameterstimezonecalendar_idrequiredworking_hoursbuffer_after_minutesbuffer_before_minutes

get_availability_rules

Read the buffer times and working-hours rules configured on a calendar. Returns the rules row, or an error if none are set.

Parameterscalendar_idrequired

clear_availability_rules

Remove the availability rules from a calendar, reverting to the default (no buffers, no working-hours mask). Returns the deleted row, or an error if none were set.

Parameterscalendar_idrequired

create_scoped_key

Create an agent-scoped API key (chr_ak_*) that can only act on behalf of a single agent. Use this to self-provision or rotate per-agent credentials. The plaintext key is returned exactly once in the response — store it immediately, it cannot be retrieved later. Requires an org-level API key.

Parameterslabelagent_idrequired

list_scoped_keys

List all live (non-revoked) agent-scoped API keys for this org. Returns key metadata only (id, prefix, agent_id, label, created_at) — never the plaintext secret. Requires an org-level API key.

Takes no parameters.

revoke_scoped_key

Revoke an agent-scoped API key by ID. Revocation is permanent (cannot be un-revoked); the key stops authenticating within about a minute. Requires an org-level API key.

Parameterskey_idrequired

create_webhook

Create a webhook subscription so the org receives HTTP POST notifications when events occur (e.g. event.created, proposal.confirmed). The signing secret is returned ONCE in this response — store it to verify the HMAC-SHA256 signature on delivered payloads. Requires an org-level API key.

Parametersurlrequiredeventsrequired

list_webhooks

List the org's webhook subscriptions with their subscribed event types and active state. Signing secrets are never returned. Requires an org-level API key.

Parameterslimitoffset

get_webhook

Get a single webhook subscription by id, including its subscribed event types and active state. The signing secret is never returned. Requires an org-level API key.

Parameterswebhook_idrequired

update_webhook

Update a webhook subscription — change its delivery URL, the set of subscribed event types, or pause/resume it via active. At least one field must be supplied. Requires an org-level API key.

Parametersurlactiveeventswebhook_idrequired

delete_webhook

Permanently delete a webhook subscription. This frees its endpoint slot against the per-plan cap. Requires an org-level API key.

Parameterswebhook_idrequired

list_webhook_deliveries

List delivery attempts for a webhook subscription, with per-status counts (pending/delivered/failed). Use this to debug failing deliveries. Requires an org-level API key.

Parameterslimitoffsetstatuswebhook_idrequiredinclude_payload

get_agent

Fetch a single agent by ID. An agent represents an AI assistant, human, or shared resource (e.g. a meeting room). Agent-scoped API keys may only read their own agent.

Parametersagent_idrequired

update_agent

Update an agent's name, description, metadata, or status (active/paused). Requires an org-level API key — agent-scoped keys cannot mutate agents.

Parametersnamestatusagent_idrequiredmetadatadescription

delete_agent

Decommission an agent. This marks the agent as decommissioned and revokes all of its scoped API keys. Requires an org-level API key — agent-scoped keys cannot delete agents.

Parametersagent_idrequired

list_calendars

List calendars in the org. Org-level API keys see every calendar (agent-owned and shared); agent-scoped keys see only their own agent's calendars. Use this to discover calendar IDs before creating or listing events.

Parameterslimitoffsetincludeagent_id

get_calendar

Fetch a single calendar by ID, including its name, timezone, agent status, and default reminders. Agent-scoped keys may only read calendars owned by their agent.

Parameterscalendar_idrequired

update_calendar

Update a calendar's name, timezone, agent status, default reminders, or metadata. Agent-scoped keys may only update calendars owned by their agent.

Parametersnamemetadatatimezonecalendar_idrequiredagent_statusdefault_reminders

delete_calendar

Delete a calendar (soft delete). Its events are no longer returned and it stops contributing to availability. Agent-scoped keys may only delete calendars owned by their agent.

Parameterscalendar_idrequired

create_booking_page

Create a public booking page (a hosted scheduling link) for a calendar. Returns a booking_url to send to a human; when they pick a slot, a confirmed event is created on the calendar and an event.created webhook fires with a booking_page_id field. Set availability_constraints to restrict to weekly working hours; existing calendar events always block slots.

Parameterstitlerequiredactivetimezonecalendar_idrequireddescriptionwindow_daysbuffer_minutesduration_minutesmin_notice_minutesavailability_constraints

list_booking_pages

List booking pages in the org. Agent-scoped keys see only pages on their own agent's calendars.

Parameterslimitoffset

get_booking_page

Fetch a single booking page by ID, including its public booking_url and settings.

Parametersbooking_page_idrequired

delete_booking_page

Delete (deactivate) a booking page. Its hosted URL stops resolving; already-booked events are unaffected.

Parametersbooking_page_idrequired

get_usage

Get the calling org's current-period usage and plan limits (agents, calendars, events, API calls, webhooks, availability queries, iCal subscriptions, proposals, scoped keys, holds, cross-calendar queries). Requires an org-level API key (chr_sk_*); agent-scoped keys cannot read org-wide usage.

Takes no parameters.

get_audit_log

List audit-log entries for the calling org — mutating operations and auth-lifecycle events, newest first. Results are clamped to the plan's retention window. Requires an org-level API key (chr_sk_*); agent-scoped keys cannot read the org-wide audit log.

Parameterstofromlimitactioncursoractor_key_prefix

accept_terms

Re-accept the current Chronary terms of service on behalf of the calling org. Use this when responses carry the Chronary-Terms-Upgrade-Required header — a material ToS bump otherwise leaves MCP-only agents stuck without a console session. Pass the current tos_version (read it from GET /v1/auth/terms/current). Requires an org-level API key (chr_sk_*); agent-scoped keys cannot accept org-wide terms.

Parameterstos_versionrequired

Version history

1
  1. v1.5.2LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts