Calendar

APX has no built-in calendar client. It reaches your agenda through MCP, the same way it reaches anything else it does not implement itself.

That is a deliberate choice rather than a gap. A calendar is the one integration where the protocols are already good, the servers already exist, and the differences between providers (Google, CalDAV, Exchange) are exactly the differences an MCP server is there to absorb.

What is NOT built yet

Calendar events are not a signal source. The watch routine detects overdue work and promises coming due from local stores, deterministically and without a model. It cannot do the same for your calendar, because reading a remote agenda means a network call, and a detector that makes network calls stops being cheap enough to run every few minutes.

So “a meeting in 30 minutes” is not something APX will interrupt you about. It reads your agenda when it runs a turn — the day-open anchor, or when you ask — which covers the useful cases and none of the proactive ones. Making it proactive needs the native adapter described at the bottom of this page.

Connect a calendar

1. Pick an MCP server for your provider. Any server implementing the Model Context Protocol works; APX does not require a specific one.

2. Register it globally, so every project and channel can reach it. Everything after -- is passed to the server as its arguments:

   apx mcp add calendar --scope global --command npx -- -y @your/calendar-mcp-server

3. Check the agent can see its tools. This also prints each tool’s arguments and a ready-to-paste Run: line, which the next section needs:

   apx mcp tools calendar

4. Ask for it in plain language. The super-agent finds MCP tools through call_mcp; you do not need to name the server.

   what's on my calendar today?

Give the agenda to the morning anchor

Asking works from the moment the server is registered. An anchor is different: a scheduled run has nobody at the keyboard, and call_mcp is a tool APX asks you to confirm. Granting it to an unattended routine would hand that routine every MCP server on the machine, write tools included — for a calendar read.

So the anchor does not call the calendar. It is handed the agenda, already fetched, by its own pre-command. The secretary profile exposes one setting for it:

apx profile config --set "calendar_command=apx mcp run calendar list_events"

If your tool needs JSON arguments — apx mcp run calendar list_events '{"timeMin":"today"}' — set it with apx profile config --interactive or in the web panel instead, so the shell does not eat the quotes.

From then on, whatever that command prints reaches the morning message inside a <calendar> block. It costs the agent no tool call, no permission, and no step out of its budget.

It degrades quietly, by design

Leave the setting blank and the anchor never mentions a calendar — no apology, no “I could not reach your agenda”. If the command fails or the server is down, its error lands in the same block and the anchor is told to treat that as “no calendar” and carry on. A calendar that is down costs you the agenda line, not your morning message.

Recommended configuration

Three things matter more than which server you choose.

Read-only unless you mean it. A server that can create and delete events gives the agent the ability to change other people’s days. Start with read scopes. Grant write access when you have a reason to, and remember that APX will still ask before an outward-facing write — sending, publishing, or changing something in a third-party system all confirm first.

Global scope, not per-project. Your calendar is not a property of one repository. A chief-of-staff profile asking “what does today look like” needs the agenda regardless of which project it is thinking about.

Keep the anchor’s command small. Its whole output is pasted into the prompt. Ask for today, not the month, and pipe a chatty server through jq if it answers with more than the times and titles.

Credentials

MCP servers hold their own credentials, usually as environment variables in the server’s own config. APX passes them through and never stores them itself. Nothing calendar-related is written to ~/.apx/config.json.

The native adapter, and why it is not here yet

The spec calls for src/core/integrations/plugins/calendar.js with normalised tools — calendar_list_events, calendar_create_event, calendar_find_slot, calendar_update_event — so a profile depends on APX’s contract rather than on whichever tool names a third-party server happens to use.

That adapter is worth building, and it is deliberately not built yet. Writing a stable contract before there is a working use case behind it is how you get an abstraction shaped like a guess. The order is: get it working through MCP, find out what a profile actually asks a calendar for, then freeze that.

Two things change when it lands. Switching providers will stop meaning “edit the calendar_command setting”, and a scoped read-only calendar tool can be allowed to a routine without that routine gaining access to every other MCP server — which is what would make “you have a call in 30 minutes” possible.