Tokens and scopes

An agent never holds power of its own: it acts with the named token it was given, and that token carries the same rules as any token created by hand from Settings › Connections and agents › Advanced access.

Read and write

A token carries one or two scopes: read and write.

• read allows reading — every GET, and write calls passed in simulation (dry_run). This is the scope for an agent you only want to trust with reading a schedule, a progress report, an export.
• write is required for everything else — every tool that places a block, moves a row, replies to a comment. A read-only token attempting one of these tools receives an explicit refusal (SCOPE_INSUFFICIENT), not a silent success.

A named token born from a POST /oauth/authorize carries the scopes the client requested at the time of authorization (the consent form displays them) — Claude Code generally requests both.

One token per client

Every OAuth client that registers (Claude Code, Claude Desktop should it go through this door, another agent) gets its own token, named after it — "MCP · Claude Code", "MCP · <client name>". It isn't a shared token: two different agents have two different tokens, two different rows under Settings › Connections and agents › Connected applications, and two different attributions in the schedule's log ("Claude (you)", or "Claude (Anne)" if the token acts on behalf of a user other than the instance's owner).

Duration: thirty days, with an automatic refresh valid for ninety days — a single-use refresh, replaced by a fresh pair on every use; the access token's secret changes, but it stays the same named token (the same identifier, the same row in preferences) as long as the client keeps refreshing on time.

Revocation

• From Settings › Connections and agents › Connected applications: revoking a named token cuts it off immediately, and closes any live /mcp session it carried on the spot — its streams, its resource subscriptions included. An agent attempting a call at the same moment gets a 401, not a lingering session.
• Through the OAuth protocol itself: POST /oauth/revoke (RFC 7009) revokes an access token, or a whole family of refreshes at once — the point Claude Code uses to log out cleanly.
• A replayed token (an authorization code or a refresh presented twice) is treated as a probable theft: the whole family of tokens descending from it is revoked instantly.

What an agent can do, and what it can't

An agent can do everything the 101 tools cover: build, modify, analyze, share, publish, export and import schedules — and, since 0.22.0, post or read their own absences (list_absences, add_absence, remove_absence, get_schedule_risks). That's deliberately broad — it's the product.

An agent cannot:

• manage tokens (/api/v1/me/tokens) or screen sessions (/api/v1/me/sessions) — an MCP client doesn't create its own tokens, nor anyone else's;
• change the password, unlink Google, or write to the profile (/api/v1/me/password, /api/v1/me/google, PUT /api/v1/me) — these routes are reserved for a user session (the screen's cookie), refused to any named token with a refusal that says so explicitly ("tokens are managed with the screen's token, not with a named token");
• export or delete the account itself, or change who you are. This isn't a restriction bolted on after the fact: among the 101 tools, none touches the account's settings (password, profile, Google, export, deletion) — those stay reserved for a user session, as above. Only your absences (since 0.22.0) are a piece of personal data a tool can post or read, because an agent should be able to say "I'm out" the way you would yourself — never another account's, and never a medical reason (the schema refuses it). The right to export and erase the whole account (GDPR) stays with the person; it isn't a capability delegated to an agent acting on their behalf, even with a write token.

(A note of caution for this repository: the account export and deletion API routes, added in sprint 16, aren't present in the branch lineage this guide is written from — see the sprint's closing notes for what that means about the state of docs/agents/. The absence of any dedicated account-related MCP tool, on the other hand, is verifiable in the current catalog regardless of that point.)

An embedded view is not a named token

In an MCP Apps host, the embedded view (show_schedule) has no token of its own: it reads and writes through the host, under the connector's named token (or OAuth). For a client that does not render MCP Apps (Claude Code), show_schedule returns an address carrying a token valid for one hour, capped to the displayed schedule and to the role of whoever requested it, read-only unless editable: true — a mechanism distinct from this page's named tokens, never visible nor revocable from Settings › Connections and agents › Connected applications. Under that token, the member list carries no e-mail address and the agenda no absence reason. It expires on its own; nothing more to remember here.