Agents
Agents and MCP
Cotask exposes one endpoint that any AI assistant can use as a tool. It speaks MCP (the Model Context Protocol) and plain REST, at the same base, with the same permissions.
https://usecotask.com/mcpTwo ways to authorize, and the endpoint accepts either:
- Sign in (OAuth 2.1) — for ChatGPT, Claude and any MCP client with a connector UI. Nothing to paste; you approve on Cotask's own consent screen.
- An agent key — for terminals, scripts and Claude Code. A
pl_…key you create in the app.
Whatever an agent creates lands in Drafts with the assistant's name and logo on it, until you accept it.
Connect ChatGPT or Claude (no key)#
- In the app: Settings → Agents → copy the MCP server URL.
- In ChatGPT or Claude: Settings → Connectors → Add custom connector (the wording differs a little per client) and paste the URL.
- The client discovers everything and sends you to Cotask's consent screen. Sign in with your Cotask account and approve.
- Ask for something: "look at my Cotask tasks and plan my week." Suggestions arrive in Drafts.
Access tokens last an hour and refresh tokens rotate on every use, so the connection keeps working without asking you again — for 90 days from when you approved it; after that the client sends you back to the consent screen. Every connection is listed in Settings → Agents → Connected assistants, with when it was approved and last used; disconnect one there and its access ends at once, on every device.
Connect Claude Code, a terminal or a script#
- Settings → Agents → New agent key, name it after the tool ("Claude Code"), and copy the key —
pl_…, shown once and never again. - Add the server:
claude mcp add --transport http cotask \
https://usecotask.com/mcp \
--header "Authorization: Bearer pl_your_key"Any MCP client that takes a JSON config wants the same three things — an HTTP transport, the URL, and the header:
{
"mcpServers": {
"cotask": {
"type": "http",
"url": "https://usecotask.com/mcp",
"headers": { "Authorization": "Bearer pl_your_key" }
}
}
}Keys are stored hashed — Cotask cannot show you one again. Each key lists its prefix and when it was last used, so an unfamiliar one is easy to spot and swipe away. Deleting a key cuts that agent off immediately; nothing it created is touched.
The tools#
| Tool | Does | Takes |
|---|---|---|
list_tasks | Lists tasks with their attachments and triggers | status, project (id or name), priority, reminder (any · urgent · notify · none), triggers (any · armed · none), query (title substring), limit (default 200, max 500) |
get_task | One task, with notes, reminder, attachments and triggers | id |
create_task | Creates a task — a draft by default | title (required), notes, status, project, due_date, priority, recurrence, remind_at, remind_in, urgent, reminder_kind, time_zone, blocked_by, triggers, attachments |
update_task | Changes only the fields passed | id (required), plus any of title, notes, status, project, due_date, priority, recurrence, remind_at, remind_in, urgent, reminder_kind, time_zone, blocked_by, triggers — null clears the optional ones. Also completion_note, the note of completion |
complete_task | Marks a task done, with an optional note of completion — notes are never touched | id (required), note (Markdown; left out, null or blank completes with no note) |
set_reminder | Sets, moves or clears when a task rings — and how loudly | task_id (required), remind_at, remind_in, urgent, reminder_kind, time_zone |
delete_task | Retracts a suggestion — drafts only | id |
add_attachment | Attaches a link; the title and favicon are resolved server-side | task_id, url, title (optional) |
attach_file | Attaches a file — bytes or a URL to fetch | task_id, one of data (base64, ≤ 8 MB) or source_url (≤ 25 MB), file_name, content_type, title |
remove_attachment | Removes a link or file (and deletes the stored file) | id |
list_projects | The user's projects | — |
create_project | Creates a project | name, color (gray, red, orange, yellow, green, teal, blue, indigo, purple, pink) |
list_delegate_routes | Your Delegate to AI routes — never where a webhook posts | — |
delegate_task | Delegates a task through a route, like the button: it starts (Doing, due today); a Mac route answers with its dispatch_id and whether a Mac is listening | task_id, route (id or name), message, params (add only), send_at / send_in |
get_delegation | How a delegation is going: a run's status, stage, error and result, or a send still waiting | id (dispatch_id or scheduled.id) |
Every tool carries MCP annotations — readOnlyHint and openWorldHint on all of them, plus destructiveHint and idempotentHint on the ones that write — and a description on every property, so a model knows what is safe without being told in a prompt.
Delegating is there for when you ask for it — "send this to Claude Code on my Mac" — and only through the routes you set up, as you set them up. See Delegate to AI.
Reminders, for agents#
An agent asked to remind you of something has no clock of yours and no idea where you are, so it is met more than half way. set_reminder is the direct way in — the same fields also live on create_task and update_task.
| Field | What it takes |
|---|---|
remind_at | 2026-09-01T09:00:00-03:00, or 2026-09-01T09:00 read on your own clock, or 2026-09-01 for 09:00 that morning, or a delay: 45m, 2h, 1h30m, 3d. null clears the reminder |
remind_in | Just the delay: 45m, 2h. For "in an hour" — needs no clock and no time zone. Wins over remind_at |
urgent | true for the alarm that rings through silent mode and Focus; false (the default) for an ordinary notification |
reminder_kind | The long form of urgent: notify or alarm |
time_zone | An IANA name, to read a zone-less remind_at somewhere else — "9am in Tokyo" is Asia/Tokyo |
Your iPhone records its own time zone to your account, which is what a timestamp with no zone is read on; until a phone has signed in, that is UTC. Two things are refused rather than written and never rung: a kind with no moment to ring at, and a moment that has already gone by — and the refusal says what time it is where you are, which is usually what the agent was missing.
Every task comes back with a reminder object as well as the raw columns:
"reminder": {
"at": "2026-09-01T12:00:00.000Z",
"kind": "alarm",
"urgent": true,
"local_time": "Tue, 1 Sep 2026, 09:00 (America/Sao_Paulo)",
"relative": "in 2 days",
"has_passed": false
}Tasks with no reminder have "reminder": null. An agent should only reach for urgent when you asked for something urgent; see Reminders.
What agents may not do: delete a task you accepted, remove an attachment you added to a task you accepted, delegate a task — to any route, now or later — create a Mac route or change how one runs, see or change a route's token or secret, change the URL of or remove a webhook that has a signing secret, or delete your account. Those are yours, and need you signed in to the app: holding an agent key yourself does not count.
Pro, for agents. An agent works inside your plan. Setting a reminder, a blocker or a note of completion, or uploading past your storage, on a Free account answers 402 — "… requires Cotask Pro. Upgrade in the app to continue." Everything already there stays readable, and clearing a value is always allowed.
Notes formatting#
Notes are plain text with light Markdown. The apps render:
- line breaks, exactly as written
-bullets and1.numbered lists[text](https://…)links, and barehttps://…URLs- inline
**bold**,*italic*andcodein backticks
They do not render headings, block quotes, code fences, tables or images. This spec is repeated in the MCP server's instructions and on the notes property of create_task and update_task, so an agent finds it wherever it looks.
For sources, attach the page instead of pasting a long URL into the notes: an attachment shows the page title and favicon and is fetchable later. For things an agent produced — a report, a chart, a CSV — use attach_file.
Note of completion#
An agent that finishes a task can say what it did and where the result is. complete_task is the direct way — it marks the task done and leaves the note in one call:
{ "id": "…", "note": "Completed, appended to doc: [Q3 plan](https://…)" }update_task does the same with status and completion_note:
{ "id": "…", "status": "done", "completion_note": "Completed, appended to doc: [Q3 plan](https://…)" }- It is a field of its own,
completion_note— separate fromnotes, which stay your brief and are never touched by it. Every task comes back with it (nullwhen there is none). - It is Markdown, stored exactly as written — nothing is trimmed, shortened or rewritten.
- Agents can always leave one. Completion notes — iPhone → Settings → Delegate to AI, Mac → Settings → Agents; off by default — only decides whether the apps show it: both tools offer the field whatever it says, and a note written while it is off is kept and appears once it is turned on. Writing one is part of Pro.
- You can leave one too, with it on: on the Mac,
⇧⏎completes the selected task and asks for its note (escskips,⌘⏎saves; on a task that is already done it opens the note to edit); on the iPhone, press and hold a task's circle. - It belongs to the completion:
update_taskaccepts it together withstatus: "done"or on a task that is already done, and refuses it on any other. Reopening the task clears it, whoever reopens it and from wherever — that is done in the database. - Each
complete_taskcall is a completion of its own: with nonote, a note left by an earlier completion is cleared;nullor a blank string clears it explicitly. - On a done task
update_taskchanges it on its own: pass a newcompletion_noteto replace it,null(or a blank string) to clear it, or leave it out to keep it.
The same field is accepted by PATCH /tasks/:id on the REST API.
Triggers, for agents#
A blocked task can carry triggers: what happens to it the moment its blocker is marked done — by you, by an agent, or by another trigger, with every app closed. Cotask runs them on its server, once, in order, and writes what they changed into the task's history as Trigger.
There is no separate tool for them. get_task (and every task list_tasks returns) shows triggers and triggers_ran_at — when they last ran, null while they wait — and list_tasks filters with triggers: "any" | "armed" | "none". create_task and update_task take triggers: the whole list, replacing the one there. To edit, pass back what get_task returned, changed; [] or null removes them all. The same list sent again changes nothing — triggers that already ran are not armed again — while any real change to the list, or a new blocker, arms them for the next completion.
| Action | Fields | Does |
|---|---|---|
due | to: today · tomorrow · weekend · next_week · none, or in_days / later with days | Moves the due date — later pushes from the task's own date |
status | to: backlog · todo · doing · done | Changes the status; done finishes it, and runs what waits on it in turn |
priority | to: low · medium · high, or null | Sets or clears the priority |
project | project (id or name) or project_id, or null | Moves it to one of your projects, or out of its project |
remind | minutes after the blocker is done, or at (HH:MM on its due day); urgent | Sets a reminder |
delegate | route (id or name) or route_id; text | Hands it to one of your Delegate to AI routes |
note | text | Appends a line to its notes |
notify | — | A push: Ready to start |
{ "id": "…", "blocked_by": "…", "triggers": [
{ "type": "due", "to": "today" },
{ "type": "status", "to": "doing" },
{ "type": "delegate", "route": "Claude Code", "text": "The spec is in — build it." }
] }What it is held to:
- Yours only. The blocker, the project and the route must all be in your account; anyone else's is not found. The task needs a blocker (
blocked_by, now or in the same call) — there is nothing else to wait for. - Routes stay yours. A
delegateaction names a route and adds instructions, nothing more: the run uses the route's own model, effort, folder and access, which only you set in the app. An action carryingmodel,effortorparamsis refused. - Checked, not skipped. Every action is validated before anything is stored; one that doesn't fit refuses the whole list, naming it (
triggers[2]: …). At most 16 actions and 16 KB, one of each kind exceptnote. - Bounded. At most 50 tasks with triggers waiting on one blocker, and no "done → done → …" chain that would finish more than 16 tasks from one completion. Beyond that, Cotask itself runs 20 at the moment a task is done and the rest within a minute, at most 60 a minute per account.
- Never in the way. Finishing the blocker always works: an action that fails is skipped, and a task finished meanwhile is left alone.
- Pro. Setting or changing triggers needs Cotask Pro — a
402otherwise. When Pro ends they stay, asleep, and run again once it is renewed; removing them is always allowed. - On the record. Every change to the list is in the task's history, under the agent that made it.