> ## Documentation Index
> Fetch the complete documentation index at: https://help.sonto.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect to AI Agents
> Connect your AI tools to Sonto with MCP
Get introduced to AI in Sonto.
If you use agentic AI tools like Claude, Codex, or Craft Agents, you can connect them to Sonto.
Once connected, your AI tool can **read your Sonto data** (like your inbox, today, and your projects) and — if you allow it — **help you make changes** (like creating tasks or updating plans).
The connection between Sonto and your AI tool is made using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro), an emerging standard that many agentic tools support. Getting started is easy.
So what can you do?
* **Quick context**: get a briefing of today, this week, or a specific project.
* **Search and review**: find tasks, check long-term plans, and spot what’s stuck.
* **Plan with more context**: connect other information sources to your agent for assisted goalsetting.
* **Hands-on changes**: create and update tasks/projects/areas/groups, and manage yearly/quarterly plans.
Some prompts to get you started:
* “What does today look like in Sonto? Include events.”
* “Open my current week and highlight anything overdue.”
* “Get my action items from these meeting notes and add them to the Summer Promo project in Sonto.”
***
## Enable MCP in Sonto
MCP support is included in the **Mac** version of Sonto.
In Sonto:
1. Open `Settings`.
2. Go to `AI`.
3. Turn on `Enable MCP`.
When off, you can configure:
* `Port` (default: `2402`)
* `Access Mode` (`Read Only` or `Read & Write`)
### Choose an access mode
#### Read Only
Pick this when you want safe visibility from your AI tool.
* AI tools can read views, projects, areas, groups, and long-term plans.
* Write tools are not exposed.
* Any write attempt is rejected.
#### Read & Write
Read & Write lets your AI tool make changes in Sonto — including deleting data.
Start with Read Only, and only switch to Read & Write once you trust your tool setup.
Pick this when you want the AI to actively manage your Sonto data.
* Includes all read tools.
* Adds write tools for task/project/area/group/plan management.
* Destructive actions require confirmation:
* Interactive confirmation when the MCP client supports elicitation, or
* Explicit `confirm_destructive: true` when interactive confirmation is unavailable.
***
## Connect an AI tool to Sonto
### Tools that support MCPB files (like Claude Desktop)
The easiest way to connect Sonto to your AI tool is using an MCP Bundle (an .mcpb file). This works in Claude Desktop.
Open `Settings` and the `AI` tab. Under MCPB, click `Reveal in Finder` and double-click the `Sonto.mcpb` file.
In your AI tool you'll enter the pairing code shown in Sonto Settings, and you're done.
### Connecting manually
In `Settings > AI`, copy the `Endpoint` shown in the `Authenticate` section (for example: `http://127.0.0.1:2402/`).
Sonto MCP listens on localhost (`127.0.0.1`) and uses HTTP transport with OAuth.
During OAuth you’ll be asked for a time-based pairing code that Sonto shows in the same Settings screen.
### Connecting to Claude Code CLI
Run:
```bash theme={null}
claude mcp add --transport http sonto http://127.0.0.1:2402/
```
Then:
1. Start Claude Code: `claude`
2. Run `/mcp`
3. Select `sonto` (it will show as unauthenticated)
4. Confirm authentication
5. Enter the pairing code when your browser opens
### Connecting to OpenAI Codex CLI
Run:
```bash theme={null}
codex mcp add Sonto --url http://127.0.0.1:2402/
```
A browser window should open asking you for the pairing code.
Get it from Sonto (`Settings > AI`).
The Codex Desktop app will automatically pick this registration up as well.
### Connecting to OpenAI Codex Desktop App
1. Open `Settings` → `MCP Servers`
2. Click `+ Add server`
3. Give the server a name (for example: `Sonto`)
4. Select `Streamable HTTP` as the transport
5. Enter `http://127.0.0.1:2402/` as the URL
Click `Save`. An `Authenticate` button will appear next to the server.
Click it and enter the pairing code from Sonto (`Settings > AI`).
### Connecting to Craft Agents
1. In Craft Agents, go to `Sources` → `MCPs`
2. Click `+`
3. When asked what to connect, enter “Connect to 'Sonto', an MCP server at [http://127.0.0.1:2402/”](http://127.0.0.1:2402/”)
4. Wait a bit, then allow opening the OAuth screen
5. Enter the pairing code from Sonto (`Settings > AI`)
***
## Connected clients
Sonto shows all connected clients in `Settings` > `AI`. You can disconnect a clients to immediately revoke access.
***
## Reference: what you can do
### Read operations
* `get_inbox`, `get_day`, `get_day_events`, `get_week`, `get_project`, `get_area`
* `list_projects`, `list_areas`, `list_groups`
* `list_long_term_plans`, `get_long_term_plan`
* `search_todos`
### Write operations
Task operations:
* `add_task`, `edit_task`, `delete_task`, `sort_tasks`
* `bulk_edit_tasks`, `bulk_delete_tasks`
* `schedule_task_event`
Structure operations:
* `add_project`, `edit_project`, `delete_project`
* `add_area`, `edit_area`, `delete_area`
* `add_group`, `edit_group`, `sort_groups`, `delete_group`
Planning metadata and cleanup:
* `edit_day`, `edit_week`
* `delete_completed_todos` (project/area scope)
Long-term planning (yearly and quarterly plans):
* `add_long_term_plan`
* `edit_long_term_plan`
* `list_long_term_plans` (defaults to active plans when no state filter is passed)
***
## Prompts and resources (optional)
You can use Sonto with tools only. Prompts and resources are optional, but useful in clients that support them.
### Prompts
Prompts are pre-packaged workflows: Sonto bundles the right data plus a strong instruction template.
Prompt families:
* Briefings (quick overview): `day_brief`, `week_brief`
* Planning (actionable plans): `day_plan`, `week_plan`
* Operational review: `inbox_triage`, `project_review`
* Long-term planning: `ltp_summary`, `ltp_status_update`, `ltp_next_actions`, `ltp_risks`, `ltp_execution_alignment`, `ltp_plan_assist`
### Resources
Resources are read-only snapshots that some MCP clients can preload before generating a response.
Examples:
* `sonto://context/today`
* `sonto://context/this_week`
* `sonto://context/day/{date}`
* `sonto://context/week/{year}/{week}`
* `sonto://plans/active`
* `sonto://projects/{project_id}/summary`
If your client does not support resources, you can ignore them and call tools directly (`get_day`, `get_week`, `get_day_events`, etc.).
***
## Important behaviour notes
* Sonto must be running to use it with your AI tools.
* `day_iso` values are local calendar day semantics (`YYYY-MM-DD`) in the current system timezone.
* Week inputs use ISO week semantics (`week` + `year`).
* `get_day_events` uses the same visible-calendar pipeline as the in-app calendar.
* Tools that offer `include_late` / `include_late_day` filtering fall back to Sonto preferences when omitted.
* `sort_tasks` follows your rollover preference for day/week late-task visibility. Sorting a day or week also normalizes visible late tasks to that day/week.
* Group `intensity` is a score from `0` to `10`; use `null` in `edit_group` to disable group intensity scoring. Group intensity is primarily used for yearly and quarterly plans.
* IDs such as `project_id`, `area_id`, `group_id`, and `plan_id` are opaque tokens returned by Sonto.
### Connecting to Claude Code CLI
Run:
```bash theme={null}
claude mcp add --transport http sonto http://127.0.0.1:2402/
```
Then:
1. Start Claude Code: `claude`
2. Run `/mcp`
3. Select `sonto` (it will show as unauthenticated)
4. Confirm authentication
5. Enter the pairing code when your browser opens
### Connecting to OpenAI Codex CLI
Run:
```bash theme={null}
codex mcp add Sonto --url http://127.0.0.1:2402/
```
A browser window should open asking you for the pairing code.
Get it from Sonto (`Settings > AI`).
Click `Save`. An `Authenticate` button will appear next to the server.
Click it and enter the pairing code from Sonto (`Settings > AI`).
### Connecting to Craft Agents
1. In Craft Agents, go to `Sources` → `MCPs`
2. Click `+`
3. When asked what to connect, enter “Connect to 'Sonto', an MCP server at [http://127.0.0.1:2402/”](http://127.0.0.1:2402/”)
4. Wait a bit, then allow opening the OAuth screen
5. Enter the pairing code from Sonto (`Settings > AI`)
***
## Connected clients
Sonto shows all connected clients in `Settings` > `AI`. You can disconnect a clients to immediately revoke access.
***
## Reference: what you can do
### Read operations
* `get_inbox`, `get_day`, `get_day_events`, `get_week`, `get_project`, `get_area`
* `list_projects`, `list_areas`, `list_groups`
* `list_long_term_plans`, `get_long_term_plan`
* `search_todos`
### Write operations
Task operations:
* `add_task`, `edit_task`, `delete_task`, `sort_tasks`
* `bulk_edit_tasks`, `bulk_delete_tasks`
* `schedule_task_event`
Structure operations:
* `add_project`, `edit_project`, `delete_project`
* `add_area`, `edit_area`, `delete_area`
* `add_group`, `edit_group`, `sort_groups`, `delete_group`
Planning metadata and cleanup:
* `edit_day`, `edit_week`
* `delete_completed_todos` (project/area scope)
Long-term planning (yearly and quarterly plans):
* `add_long_term_plan`
* `edit_long_term_plan`
* `list_long_term_plans` (defaults to active plans when no state filter is passed)
***
## Prompts and resources (optional)
You can use Sonto with tools only. Prompts and resources are optional, but useful in clients that support them.
### Prompts
Prompts are pre-packaged workflows: Sonto bundles the right data plus a strong instruction template.
Prompt families:
* Briefings (quick overview): `day_brief`, `week_brief`
* Planning (actionable plans): `day_plan`, `week_plan`
* Operational review: `inbox_triage`, `project_review`
* Long-term planning: `ltp_summary`, `ltp_status_update`, `ltp_next_actions`, `ltp_risks`, `ltp_execution_alignment`, `ltp_plan_assist`
### Resources
Resources are read-only snapshots that some MCP clients can preload before generating a response.
Examples:
* `sonto://context/today`
* `sonto://context/this_week`
* `sonto://context/day/{date}`
* `sonto://context/week/{year}/{week}`
* `sonto://plans/active`
* `sonto://projects/{project_id}/summary`
If your client does not support resources, you can ignore them and call tools directly (`get_day`, `get_week`, `get_day_events`, etc.).
***
## Important behaviour notes
* Sonto must be running to use it with your AI tools.
* `day_iso` values are local calendar day semantics (`YYYY-MM-DD`) in the current system timezone.
* Week inputs use ISO week semantics (`week` + `year`).
* `get_day_events` uses the same visible-calendar pipeline as the in-app calendar.
* Tools that offer `include_late` / `include_late_day` filtering fall back to Sonto preferences when omitted.
* `sort_tasks` follows your rollover preference for day/week late-task visibility. Sorting a day or week also normalizes visible late tasks to that day/week.
* Group `intensity` is a score from `0` to `10`; use `null` in `edit_group` to disable group intensity scoring. Group intensity is primarily used for yearly and quarterly plans.
* IDs such as `project_id`, `area_id`, `group_id`, and `plan_id` are opaque tokens returned by Sonto.