Connect AI assistants to Iris
Iris speaks the Model Context Protocol, so Claude and other MCP-capable assistants can read your plan and act on it — with permissions you choose, and a full activity log.
Setup
Add Iris as a remote MCP server / custom connector in your AI client:
https://www.iris-plan.com/api/mcp
- In Claude (web, desktop, or mobile): Settings → Connectors → Add custom connector, paste the URL above.
- Your client discovers Iris's sign-in automatically and opens a browser window. Sign in with your normal Iris account.
- Choose what the assistant may access — per area, read-only or read & write — then Authorize.
Manage or revoke access anytime in Settings → Connections. Revocation takes effect on the assistant's very next request.
Permissions
Permissions are chosen on the Iris consent screen, not in the OAuth scope box — if your client asks for OAuth scopes, leave the defaults. Each area can be off, read-only, or read & write:
- Tasks — Tasks, subtasks, and task lists
- Calendar — Calendar events, including recurring series
- Focus — The FOCUS list — what you're working on right now
Profile basics (name, timezone) are always shared with a connected app. Meeting recordings, transcripts, and your Iris chat history are never accessible over MCP, under any permission.
Available tools
| Tool | What it does | Needs |
|---|---|---|
| iris_get_context | Timezone, defaults, task lists, calendars, scheduling preferences | Profile |
| iris_search | Keyword search across tasks, lists, events, calendars | Any read |
| iris_list_tasks | List tasks with filters | Tasks: read |
| iris_list_events | List events in a window (recurring series expanded) | Calendar: read |
| iris_focus | Read or change the focus list | Focus |
| iris_create_task | Create a task, optionally with subtasks | Tasks: write |
| iris_update_task | Edit or complete a task | Tasks: write |
| iris_create_task_list | Create a task list | Tasks: write |
| iris_create_event | Create an event or recurring series | Calendar: write |
| iris_update_event | Edit an event, an occurrence, or a series | Calendar: write |
| iris_auto_schedule | Propose (or create) time blocks for unscheduled tasks | Tasks: read (+ Calendar: write to apply) |
| iris_delete_task | Delete one task and its subtasks | Tasks: write |
| iris_delete_event | Delete one event or occurrence | Calendar: write |
Conventions for tool builders
- Times. Every datetime is an absolute ISO-8601 instant with an explicit
Zor±HH:MMoffset. Date-only fields (YYYY-MM-DD) resolve in the user's timezone, whichiris_get_contextreturns. - Recurring events. Occurrences carry synthetic ids of the form
<master-uuid>#<start-iso>. Pass them back verbatim to change one occurrence; usescope: this | this_and_future | allto widen. - Deletes. There is no bulk delete. Delete tools remove exactly one task or event per call and cannot be undone.
- Rate limits. Requests are rate-limited per user and per client; 429 responses carry
Retry-After.
Security & data handling
- Authorization uses OAuth 2.1 with PKCE. Iris never shows your password to the connected app, and access tokens expire after one hour with automatic refresh.
- Permissions are enforced twice: in the Iris API layer, and independently by row-level security in the database — a token without a permission physically cannot touch those rows.
- Every tool call is written to an append-only activity log (visible in Settings → Connections). The log records what happened — never the content of your data.
- Disconnecting an app in Settings blocks its next request immediately. A global "sign out everywhere" additionally invalidates refresh tokens; an already-issued access token can remain valid for up to one hour.
Questions or issues? Contact us.