# MCP tools

Char's MCP server is hosted. There is no local server to launch.

Endpoint: `https://api.char.com/v2/mcp`. Transport: Streamable HTTP. Authentication: Char OAuth; see [setup](setup.md). Connecting an agent from **Settings → Apps** in Char Next writes this address for the user, and the agent asks them to sign in the first time it connects.

Each tool's description, `inputSchema` and `outputSchema` come from the server's `tools/list` and are the source of truth; this page is a map. Answers carry `structuredContent`, and times are ISO 8601.

## Access

| Scope          | Allows                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `char:read`    | Required. Every read: Pages, meetings and transcripts, todos, contacts, chats, Schedules, Skills, History   |
| `char:write`   | Create and edit Pages, todos, contacts and projects, suggest work, rename and archive chats, add to History |
| `char:delete`  | Delete Pages, contacts and todos, and merge contacts                                                        |
| `char:charlie` | Change what Charlie does on its own (Skills, Schedules), and run Schedules, which uses the user's credits   |

A call that needs a scope the token lacks gets HTTP 403 with an `insufficient_scope` challenge naming `char:read` and the scope it needs. A client that supports step-up asks the user to approve it.

Skills are Pages too. A write that names a Skill's Page, through any tool, needs `char:charlie`.

## Listed by default

| Tool                      | Scope         | What it does                                                                                                                      |
| ------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `agenda_get`              | `char:read`   | The user's local date and time, and today's and tomorrow's events                                                                 |
| `calendar_list_events`    | `char:read`   | Events from the user's connected calendars                                                                                        |
| `pages_search`            | `char:read`   | Pages whose title or text contains the query, with a snippet                                                                      |
| `pages_read`              | `char:read`   | A Page's Markdown with a block ID marker before each top-level block, its todos and `sourceRevision`; `nextOffset` for long Pages |
| `pages_create`            | `char:write`  | A new Page from a title and Markdown                                                                                              |
| `pages_edit`              | `char:write`  | Append, replace, insert after or delete top-level blocks, 1–16 per call                                                           |
| `todos_list`              | `char:read`   | Open todos across Pages, by `due` or a `from`/`to` day range                                                                      |
| `todos_add`               | `char:write`  | An open todo at the end of a Page                                                                                                 |
| `pages_set_todo_status`   | `char:write`  | Marks a todo done or open again                                                                                                   |
| `todos_suggest`           | `char:write`  | Files suggested work at the top of Home, the way a meeting's follow-ups are                                                       |
| `meetings_list`           | `char:read`   | Meetings by title words or date, latest first                                                                                     |
| `meetings_get`            | `char:read`   | What was written in a meeting, its summary, participants and calendar event                                                       |
| `meetings_get_transcript` | `char:read`   | A meeting's transcript, one `[m:ss] Speaker: text` line per segment                                                               |
| `contacts_search`         | `char:read`   | People, organizations, projects or meetings by name                                                                               |
| `contacts_get`            | `char:read`   | One person or organization contact                                                                                                |
| `history_read_day`        | `char:read`   | History day by day, with each part of the day's summary and its atoms                                                             |
| `tools_search`            | `char:read`   | Finds the other tools by words; each result has its kind, scope and `inputSchema`                                                 |
| `tools_read`              | `char:read`   | Runs a read tool found with `tools_search`                                                                                        |
| `tools_write`             | `char:write`  | Runs a write tool found with `tools_search`                                                                                       |
| `tools_delete`            | `char:delete` | Runs a delete tool found with `tools_search`                                                                                      |

`tools_read`, `tools_write` and `tools_delete` take `{"name": "<tool>", "arguments": {...}}`. Each runs only its own kind of tool, so a client's approval prompt matches what the call does. A client with its own tool search can list every tool at once from `https://api.char.com/v2/mcp?tools=all`.

## Found with tools_search

- **Pages**: `pages_list`, `pages_check_revision`, `pages_links`, `pages_list_versions`, `pages_read_version`, `pages_restore_version`, `pages_rename_note`, `pages_set_appearance`, `pages_propose_edits` (a Scratchpad the user applies or discards), `pages_delete`.
- **Todos**: `pages_complete_todo_with_result`, `pages_rename_todo`, `pages_set_todo_due`, `pages_move_todo`, `pages_move_todo_to_page`, `todos_delete`.
- **Meetings**: `meetings_file_follow_ups`.
- **Contacts and entity pages**: `entities_read`, `contacts_create`, `contacts_update`, `entities_set_property`, `entities_add_identifier`, `entities_remove_identifier`, `contacts_merge`, `contacts_delete`.
- **Chats**: `chats_list`, `chats_rename`, `chats_set_read_state`, `chats_archive`, `chats_restore`.
- **History**: `history_search`, `history_read_atom`, `memory_inspect_source`, `history_read_preferences`, `history_remember`.
- **Schedules**: `schedules_list`, `schedules_get`, `schedules_history`, `reminders_list_upcoming`, `schedules_create`, `schedules_update`, `schedules_pause`, `schedules_resume`, `schedules_run_now`, `schedules_archive`.
- **Skills**: `skills_list`, `skills_read`, `skills_save`, `skills_set_enabled`.

## Pages

The read tools cover every live Page in the signed-in account: Home, daily pages, the user's Pages, and entity pages for people, organizations, projects and meetings. Attachments and recordings are not exposed. Every tool that takes a Page ID also takes a Page link (`https://char.com/p/<pageId>`). Home is `pageId` `home`, and a daily page is `daily-YYYY-MM-DD` in the user's time zone.

`pages_search` matches the whole query as one exact phrase in titles and text, and returns up to 25 Pages. So does `history_search`, across History, Pages and chats: neither finds anything by meaning, so search a name or one distinctive word, then the other words the user may have used. A meeting's transcript isn't in its Page; read it with `meetings_get_transcript`, which returns 300 segments by default and at most 1,000; pass `nextOffset` as `offset` to continue.

## Todos

`todos_list` narrows by `due` (`overdue`, `today`, `tomorrow` or `week`) or by a `from`/`to` day range, and returns up to 200 todos with `limit`. `todos_add` takes a `pageId`, one line of `titleMarkdown` and an optional `due` of `YYYY-MM-DD`, `today` or `tomorrow`. Use the todo tools for todos rather than writing checkboxes with `pages_edit`.

`todos_suggest` files work the user didn't ask for at the top of Home, the way Char files a meeting's follow-ups: one collapsible per group, headed by its one-line `titleMarkdown`, with its `sourceLabel` and optional `sourceUrl`, and 1–10 todos inside that the user accepts or dismisses one by one. It takes 1–20 groups. It is the only way to suggest a todo: `todos_add` adds only todos the user asked for. Suggest only what is both urgent and important, most important first, and never write suggested todos into a Page. A source suggested before takes only the todos it doesn't hold yet. The `suggest` Skill (`skills_read` with `name` `suggest`, through `tools_read`) holds the rest: what is worth suggesting, how to group by request and which source to show.

## Writing

`pages_read` returns the block IDs and `sourceRevision` that `pages_edit` needs. `pages_edit` takes 1–16 operations applied in one step:

- `append` with `markdown` and an optional `placement` of `start` or `end`. It needs no revision.
- `replace` or `insert-after` with a `blockId` and `markdown`.
- `delete` with a `blockId`.
- `move`, `set-collapsed` and `remove-card` go in a call of their own.

Pass `sourceRevision` for `replace`, `insert-after` and `delete`; the edit is refused if the Page changed since, from any device: read it again and retry. Edits land as suggestions the user accepts or undoes. A block edit can't add a Page chip; `pages_create` turns each bare `char://page/<pageId>` in its Markdown into one. `pages_delete` refuses a meeting's Page, which the user deletes in Char.

A tool that adds something (`pages_create`, `todos_add`, `todos_suggest`, `pages_propose_edits`, `meetings_file_follow_ups`, `contacts_create`, `history_remember`, `schedules_create`, `schedules_run_now`) requires a `requestId`. Every other write takes one too. A retry with the same `requestId` from the same app has one effect. Writes sync to every device.

A Schedule an agent creates is a proposal the user turns on in Char. `history_remember` adds what the user asked you to remember; it can't correct what History holds.

## Errors

A refused call returns `isError` with what to do next in its text, for example to read the Page again or to find an ID with a list or search tool. "Char is temporarily unavailable." means a server-side failure: retry later.
