AI Agents (MCP)

Available on every plan

MCP works on all plans. Free and Basic get read-only access to all 10 read tools (Free is limited to 100 requests a day). Pro and Ultra get full Read & Write access (27 tools) and can switch to read-only mode if they prefer.

MCP (Model Context Protocol) lets you connect AI assistants such as ChatGPT and Claude, coding assistants, and automation tools directly to your TellDone data. Once connected, your assistant can read your notes, tasks, events, reports, tags, and change history. On Pro and up, it can also create, update, delete, and restore items. There are 27 tools: 10 for reading (every plan) and 17 for writing (Pro and up).

On the iPhone, Settings > Integrations > AI Agents (MCP) opens the MCP setup screen with your access token masked by default:

And on the web:

Two ways to connect

There are two ways to connect an AI client:

1. Sign in with TellDone (OAuth) (recommended) - you sign in with your TellDone account and approve what the app asks for. ChatGPT and Claude use this, and there's no token to copy.
2. Bearer token - copy your access token from Settings and paste it into your client's config. Simplest for scripts, command-line tools, and clients that don't have a built-in OAuth flow.

Client	Recommended
ChatGPT (chatgpt.com on a computer)	OAuth - add a custom MCP server with the MCP URL, then sign in
Claude (website, Desktop, iPhone app) / Cowork	OAuth - add a custom connector with the MCP URL, then sign in
Claude Code (CLI)	Bearer token for now - add the Authorization header with your token
Scripts or your own code	Bearer token - simplest to automate
A client that only supports picking from a directory of listed connectors	Add TellDone as a custom connector with the MCP URL, or use a bearer token. TellDone isn't in any connector directory yet

Plan requirements

Plan	MCP
Free	Read-only (10 read tools), 100 requests a day
Basic	Read-only (10 read tools), no daily limit
Pro	Read & Write (27 tools) - can switch to Read-only mode
Ultra	Read & Write (27 tools) - can switch to Read-only mode

The 100-requests-a-day limit on Free counts tool calls only. Connecting, signing in, and listing tools don't count. The day follows the time zone saved in your account and resets at midnight. When you reach the limit, your assistant gets a message saying so. Write tools are refused on Free and Basic. With an access token, they reply that the connection is read-only and that creating and editing needs Pro and up. With sign-in (OAuth), most of them reply "Insufficient scope", because Free and Basic connections never get write permissions.

The in-app screen

Open Settings > Integrations, and in the AI Agents section tap AI Agents (MCP). The screen says "Let ChatGPT, Claude, and other AI assistants work with your TellDone notes, tasks, and events." and shows your plan:

• Free: "Your plan: Read-only access, 100 requests a day. Writing comes with Pro."
• Basic: "Your plan: Read-only access"
• Pro and Ultra: "Your plan: Read & Write access"

While MCP is off, tap Enable to turn it on.

Once enabled, the screen shows:

• Access mode (Pro and Ultra) - choose Read-only or Read & Write at any time.
• Connect an assistant - steps for ChatGPT, Claude, and Another assistant. You sign in to TellDone inside the assistant, so no token is needed.
• Connected apps - the assistants you have connected, each with a Disconnect button. It stays empty until the first connection.
• For developers (collapsed by default) - the Access Token field (hidden, with Show / Hide and Copy), Regenerate Token, and a Claude Code / Cursor / Other switch with ready-made text and its own Copy button. Claude Code gives you the claude mcp add command, Cursor gives you the JSON for .cursor/mcp.json, and Other lists the server address, the OAuth sign-in option, and the Authorization: Bearer header. While the token is hidden, the snippets show YOUR_TOKEN. Tap Show and they contain your real token.

The web has the same controls in a different layout, with no collapsed developer section: the OAuth address with a Copy button, your token controls, Connected apps with Disconnect, and Manual bearer token setup with six client choices (Claude Code, Cursor, Windsurf, Codex, OpenClaw and cURL). On the web, the snippets always contain your real token, even while the token field is hidden, so treat them like the token itself.

• Documentation - a link to this page.
• Disable - turns MCP off. You confirm with "This will revoke access for all connected AI tools." Your token is deleted and all connections stop. If you enable MCP again, you get a new token, and apps connected with sign-in (OAuth) work again without signing in. To remove an app for good, tap Disconnect under Connected apps.

tip

Keep your access token private. Anyone with the token can access your TellDone data. Tap Regenerate Token if you ever suspect it has leaked.

How to enable

You can configure MCP from either platform:

• iPhone: Settings > Integrations > AI Agents (MCP)
• Web: app.telldone.app > Settings > Integrations > AI agents (MCP)

Steps:

1. Tap Enable.
2. On Pro and Ultra, choose your access mode (Read-only or Read & Write). Free and Basic are read-only.
3. To connect ChatGPT or Claude, tap it under Connect an assistant and follow the steps (see below). No token is needed.
4. For a coding client on iPhone, open For developers, tap Show, pick Claude Code, Cursor, or Other, and tap Copy under the snippet. If you copy before tapping Show, the snippet has YOUR_TOKEN in place of your token. On the web, pick your client under Manual bearer token setup and copy the snippet; it already contains your token.
5. Paste the snippet into your client or its config file.

Connecting with OAuth

OAuth is the recommended path for ChatGPT, Claude, and Cowork - you sign in with your TellDone account instead of copying a token.

MCP URL for OAuth: https://api.telldone.app/mcp/user

The same server also answers at https://api.telldone.app/mcp/user/mcp, and both addresses accept a bearer token. For OAuth sign-in, use the first one.

ChatGPT

Custom MCP servers can be added only on chatgpt.com in a computer browser. The app puts it this way: "The ChatGPT app only adds connectors from its catalog. Add TellDone once on chatgpt.com in a desktop browser." Tap Send the steps to my computer to get the instructions there. Once added on the web, TellDone is available in the ChatGPT app too.

The steps in the app:

1. On a computer, open chatgpt.com/plugins, click Add and choose Add custom MCP server.
2. Name it TellDone, paste the address below (https://api.telldone.app/mcp/user) and choose OAuth.
3. Confirm and install it, then sign in to TellDone and allow access.

See OpenAI's guide on custom MCP servers if the menu names change.

Claude (website, Desktop, iPhone app) / Cowork

The steps in the app:

1. In Claude, open Customize → Connectors and tap Add custom connector.
2. Paste the address below (https://api.telldone.app/mcp/user).
3. Sign in to TellDone and allow access.

When you sign in, TellDone's consent page shows which app is asking for access and the exact permissions it wants. Sign in with your TellDone email and password and click Allow access, or tap Sign in with Apple or Sign in with Google, which approves the access in the same step. Claude connects on its own - there's no token to copy.

If the menu names change, see Anthropic's guide on adding a custom connector.

Connecting with a bearer token

For Claude Code, Cursor, and other clients without built-in OAuth sign-in, paste your access token directly into the client's config. Replace YOUR_TOKEN with the token from your settings in all examples below.

Claude Code (bearer token)

claude mcp add --transport http telldone \
  https://api.telldone.app/mcp/user/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

You don't have to type this yourself: in Settings > Integrations > AI Agents (MCP) > For developers, tap Show, choose Claude Code, and tap Copy. The copied command already contains your token.

Cursor

Add to .cursor/mcp.json (or copy it from For developers > Cursor after tapping Show):

{
  "mcpServers": {
    "telldone": {
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Other clients

Settings for other MCP clients:

Codex

Add to codex.json:

{
  "mcpServers": {
    "telldone": {
      "type": "http",
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

OpenClaw

Settings > MCP Servers > Add:

• Name: TellDone
• URL: https://api.telldone.app/mcp/user/mcp
• Auth: Bearer YOUR_TOKEN

Other MCP clients

Any tool that supports MCP over HTTP can connect. Use the endpoint https://api.telldone.app/mcp/user/mcp with a Bearer YOUR_TOKEN authorization header.

Alternative auth header

If your client or proxy reserves the Authorization header (for example, some Smithery-style gateways), send the token in X-MCP-Token: YOUR_TOKEN instead. Both headers work; if both are present, Authorization wins.

Testing your connection

You can verify your token works with a simple cURL command:

curl -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

A successful response lists all available tools.

Permissions (scopes)

OAuth connections are scoped - during sign-in you see exactly what the client is asking for and approve it explicitly.

Scope	Lets the app...
notes:read	Read your notes and open full note details (the search tool also needs tasks:read and events:read)
notes:write	Create, edit and delete notes (process_note also needs tasks:write and events:write)
tasks:read / tasks:write	Read / create, edit, complete, and delete tasks
events:read / events:write	Read / create, edit, and delete events
reports:read	Read your daily, weekly, monthly, and yearly reports
tags:read / tags:write	List your tags / create, pin, delete, and restore tags
profile:read	Read your account info and subscription
offline_access	Stay signed in (issues a refresh token so you don't have to sign in again each session)

Scopes limit what a connection can do: a connection with only notes:read can't call a write tool. Your plan sets a second limit on top.

Bearer-token connections aren't scoped individually - they're governed by your plan's read/write mode only.

What you can do

Read tools (10) - all plans

Tool	What it does
get_notes	List notes with filters (tags, date range, text search)
get_note	View a single note with its child tasks, events, and full transcript
get_notes_full	Get multiple notes with embedded tasks and events in one call
get_tasks	List tasks filtered by status (to-do, done, all), tags, or dates
get_events	List calendar events, filter by date range
get_reports	Read your daily, weekly, monthly, and yearly reports (full markdown)
get_tags	View all your tags sorted by usage
get_profile	See your account info and how many notes, tasks and events you have
search	Search across notes, tasks, and events (text + semantic search for notes)
get_change_log	See the edit history of a note, task, or event, and whether each edit has been undone

tip

The search tool supports semantic search for notes - it finds results by meaning, not just keywords. For example, searching "meetings about budget" will find notes about financial discussions even if they don't contain the word "budget."

Write tools (17) - Pro and Ultra

Tool	What it does
process_note	Full AI pipeline - send text or audio, get back a note with tasks, events, and tags
create_note	Add a plain text note (no AI analysis)
create_task	Add a task with priority, deadline, reminder, and tags
create_event	Add a calendar event with date, time, location, reminders, attendees, and repeat rule
update_note	Change note title, summary, type, tags, priority, or status
update_task	Change task title, description, priority, deadline, reminder, tags, or status
complete_task	Mark a task as done
update_event	Change event details, time, location, reminders, attendees, repeat rule, tags, or status
delete_note	Delete a note and all its linked tasks and events
delete_task	Delete a task
delete_event	Delete an event
undo_change_log_entry	Undo a single tracked edit - AI-made or your own - restoring the field's prior value
restore_entity	Bring back a deleted or archived note or task, or a deleted or canceled event
create_tag	Create a new tag, or turn an auto-suggested tag into a permanent one
set_tag_pinned	Pin or unpin a tag so it sorts to the top
delete_tag	Remove a tag (can be restored with restore_tag)
restore_tag	Bring back a deleted tag

All write and delete operations appear right away on your connected devices (phone, web app).

Tools reference

get_notes

List notes with optional filtering. Date filters use recorded_at (when you recorded the voice note), or created_at for a note that has none.

Parameter	Type	Default	Description
limit	int	20	Number of notes to return (max 50)
offset	int	0	Skip this many notes (for pagination, max 10000)
tags	string	-	Filter by tags, comma-separated (matches any)
search	string	-	Text search on title and summary
date_from	string	-	Start date, YYYY-MM-DD (inclusive)
date_to	string	-	End date, YYYY-MM-DD (exclusive)
standalone_only	bool	false	When true, hides follow-up notes (notes attached to a parent note/task/event) and returns only standalone notes

Returns: list of notes with id, title, summary, type, tags, priority, status, recorded_at, created_at.

get_note

Get a single note with its full transcript and all linked tasks and events.

Parameter	Type	Description
note_id	string	The note's UUID

Returns: note with title, summary, transcript, type, tags, priority, status, metadata, created_at, plus tasks[] and events[] arrays.

Also returns transcript_speakers (speaker-labeled transcript turns, for meetings with several speakers - null otherwise), speaker_count (null unless the recording was split by speaker), and parent_note_id/parent_task_id/parent_event_id (set when this note is a follow-up edit of another item). Each tasks[]/events[] entry also includes reminders_at/recurrence_rule (tasks) or reminder_minutes/attendees/recurrence_rule (events).

get_notes_full

Get multiple notes with their tasks and events in a single call. Same filters as get_notes except search, and each note includes embedded tasks[] and events[].

Parameter	Type	Default	Description
limit	int	10	Number of notes (max 20)
offset	int	0	Skip this many notes
tags	string	-	Filter by tags
date_from	string	-	Start date, YYYY-MM-DD
date_to	string	-	End date, YYYY-MM-DD
standalone_only	bool	false	When true, hides follow-up notes (notes attached to a parent note/task/event) and returns only standalone notes

get_tasks

List tasks with filtering.

Parameter	Type	Default	Description
status	string	"todo"	Filter: todo, done, or all
limit	int	30	Number of tasks (max 100)
offset	int	0	Skip this many tasks
tags	string	-	Filter by tags, comma-separated
date_from	string	-	Start date, YYYY-MM-DD (filters by deadline; tasks without a deadline are excluded)
date_to	string	-	End date, YYYY-MM-DD (filters by deadline; tasks without a deadline are excluded)

Returns: list of tasks with id, title, description, status, priority, tags, deadline, reminder_at, reminders_at, completed_at, completed_by, source, created_at. reminder_at mirrors the first entry of reminders_at for backward compatibility - use reminders_at to see all of a task's reminders.

get_events

List calendar events with date range filtering.

Parameter	Type	Default	Description
limit	int	30	Number of events (max 100)
offset	int	0	Skip this many events
date_from	string	-	First day, YYYY-MM-DD, in your own time zone (inclusive). Events that overlap the range are included, so a multi-day event shows on every day it covers
date_to	string	-	Last day, YYYY-MM-DD, in your own time zone (inclusive)

Returns: list of events with id, title, description, status, start_at, end_at, location, is_all_day, tags, note_id, reminder_minutes, attendees, recurrence_rule, created_at.

get_reports

Get your AI-generated reports with full markdown content.

Parameter	Type	Default	Description
report_type	string	"daily"	Type: daily, weekly, monthly, or yearly
limit	int	5	Number of reports (max 10)

Returns: list of reports with id, type, period_start, period_end, content_md, created_at.

note

Monthly reports are long (often well over 1,000 words). Use limit=1 if your AI tool has a tight context window.

get_tags

Get all your tags, sorted by pinned first, then by usage count.

No parameters. Returns up to 100 tags, each with tag, usage_count, is_pinned, is_manual.

get_profile

Get your account info and how many notes, tasks and events you have.

No parameters. Returns email, display_name, locale, transcription_locale, timezone, subscription, mcp_mode, created_at, and stats (note/task/event counts).

search

Search across notes, tasks, and events at once. For notes, supports both text search and semantic search (finds results by meaning using AI embeddings).

Parameter	Type	Default	Description
query	string	required	Search text (max 500 characters)
limit	int	20	Max results per type (max 20)
semantic	bool	true	Enable semantic search for notes

Returns results grouped by type: notes[], tasks[], events[]. Each result has id, type, title, detail, created_at.

Set semantic=false for faster text-only search.

get_change_log

See the edit history of a note, task, or event - every AI-made follow-up edit and every manual edit you made yourself, newest first.

Parameter	Type	Default	Description
entity	string	required	notes, tasks, or events
entity_id	string	required	The item's UUID
include_manual	bool	false	Also include your own manual edits, not just AI-made ones

Returns: list of change entries with id (use this as entry_id for undo), field_name, old_value, new_value, source (follow_up, smart_context, correction_sync for a name fix TellDone carried across a note, or manual), origin_note_id, edited_at, and reverted_at (set once undone).

process_note (Pro and Ultra)

Full AI pipeline - works the same as recording in the app. Send text or audio, and TellDone will transcribe, analyze with AI, and create a structured note with extracted tasks, events, tags, and embeddings.

This tool is asynchronous: it returns immediately with an audio_id and processes in the background. Results arrive via real-time sync to your connected devices, or you can poll with get_notes().

Parameter	Type	Description
text	string	Required. Text to analyze. If it is not empty, it is used as the transcript and any audio you send is not transcribed; send "" to have the audio transcribed. Limit when no audio is sent: Pro 20,000 / Ultra 50,000 characters
audio_base64	string	Base64-encoded audio file. The whole request is limited to 10 MB, so the audio itself can be about 7 MB. It is transcribed only when text is empty
audio_format	string	m4a, ogg, wav, mp3, aac, or webm (default: m4a)
parent_task_id	string	UUID of a task this is a follow-up to
parent_note_id	string	UUID of a note this is a follow-up to
parent_event_id	string	UUID of an event this is a follow-up to

Always send text. To have TellDone transcribe audio, send audio_base64 with text set to an empty string (""). If text is not empty, TellDone uses it as the transcript and does not transcribe the audio. Set at most one of the three parent IDs.

Returns: {"audio_id": "...", "status": "processing", "mode": "text-only"} or "mode": "audio+stt" if audio was provided.

note

process_note is subject to your plan's quotas (uploads per day, notes per month, max text length). get_profile shows only how many notes, tasks and events you have, not your limits. Check your usage in the app under Settings > Usage.

create_note (Pro and Ultra)

Create a plain text note instantly. Does not trigger AI analysis - no tasks or events are extracted. Use process_note when you want TellDone to find tasks and events for you.

Parameter	Type	Limit	Description
title	string	200 chars	Required
summary	string	1000 chars	Optional. Short teaser (1-3 sentences). Used in your reports, so keep it short
transcript	string	plan-based	Optional. Long-form body shown in the note detail. Not included in reports. Limits: Pro 20,000 / Ultra 50,000 chars
type	string	-	Optional. task, idea, info (default), status, meeting, event, or reflection
tags	string	20 tags	Comma-separated, optional

create_task (Pro and Ultra)

Create a new task.

Parameter	Type	Limit	Description
title	string	200 chars	Required
description	string	2000 chars	Optional
priority	string	-	low, medium (default), or high
deadline	string	-	YYYY-MM-DD, optional
reminder_at	string	-	ISO 8601 datetime (for example 2026-04-15T09:00:00Z), optional
tags	string	20 tags	Comma-separated, optional
note_id	string	-	UUID to link task to a parent note, optional

create_event (Pro and Ultra)

Create a calendar event.

Parameter	Type	Limit	Description
title	string	200 chars	Required
start_at	string	-	ISO 8601 datetime, required
end_at	string	-	ISO 8601 datetime (default: start + 1 hour; for an all-day event, one day)
description	string	2000 chars	Optional
location	string	200 chars	Optional
is_all_day	bool	-	Default: false
tags	string	20 tags	Comma-separated, optional
reminder_minutes	string	-	Comma-separated minutes before event (for example 15,60), optional
attendees	string	-	Comma-separated names or emails, optional
recurrence_rule	string	-	RRULE string (for example FREQ=WEEKLY;BYDAY=MO,WE,FR), optional. Rules more frequent than hourly, or that can never happen, are refused
note_id	string	-	UUID to link event to a parent note, optional

update_note (Pro and Ultra)

Update one or more fields on an existing note. Only fields you provide are changed.

Parameter	Type	Description
note_id	string	Required, the note's UUID
title	string	New title (max 200 chars)
summary	string	New summary (max 1000 chars, pass a space " " to clear)
transcript	string	New transcript (plan-based limit, pass a space " " to clear)
type	string	task, idea, info, status, meeting, event, or reflection
tags	string	Comma-separated tags (replaces all existing tags, max 20)
priority	string	low, medium, or high
status	string	active or archived

caution

For notes created by the voice pipeline, transcript is the original speech-to-text output. Overwriting it replaces your original words. To keep them, add to the transcript instead of replacing it.

update_task (Pro and Ultra)

Update one or more fields on an existing task. Only fields you provide are changed.

Parameter	Type	Description
task_id	string	Required, the task's UUID
title	string	New title
description	string	New description (pass a space " " to clear)
priority	string	low, medium, or high
deadline	string	YYYY-MM-DD. This tool can't clear a deadline; clear it in the app
status	string	todo or done
tags	string	Comma-separated tags (replaces all existing tags, max 20)
reminder_at	string	ISO 8601 datetime (pass a space to clear)

Setting status to done also records when and how the task was completed.

complete_task (Pro and Ultra)

Shortcut to mark a task as done.

Parameter	Type	Description
task_id	string	Required, the task's UUID

Returns an error if the task doesn't exist or is already completed.

update_event (Pro and Ultra)

Update one or more fields on an existing event. Only fields you provide are changed.

Parameter	Type	Description
event_id	string	Required, the event's UUID
title	string	New title
description	string	New description (pass a space to clear)
start_at	string	New start time (ISO 8601)
end_at	string	New end time (ISO 8601)
location	string	New location (pass a space to clear)
status	string	confirmed, tentative, or cancelled
tags	string	Comma-separated tags (replaces all existing tags, max 20)
is_all_day	string	"true" or "false"
reminder_minutes	string	Comma-separated minutes before event (for example 15,60, pass a space to clear)
attendees	string	Comma-separated names or emails (pass a space to clear)
recurrence_rule	string	RRULE string (pass a space to clear)

delete_note (Pro and Ultra)

Delete a note. This also deletes all tasks and events that were created from this note.

Parameter	Type	Description
note_id	string	Required, the note's UUID

delete_task (Pro and Ultra)

Delete a task.

Parameter	Type	Description
task_id	string	Required, the task's UUID

delete_event (Pro and Ultra)

Delete an event.

Parameter	Type	Description
event_id	string	Required, the event's UUID

undo_change_log_entry (Pro and Ultra)

Undo a single tracked edit - restores the field to its value before that edit, whether the edit was made by the AI (from a follow-up recording) or by you directly.

Parameter	Type	Description
entity	string	Required, notes, tasks, or events
entity_id	string	Required, the item's UUID
entry_id	string	Required, the change entry's id from get_change_log

Returns: {"entry_id", "entity_type", "entity_id", "field_name", "restored_value", "reverted_at"}. Undoing the same entry twice returns an error - it's already undone.

restore_entity (Pro and Ultra)

Bring back a deleted or archived note or task, or a deleted or canceled event.

Parameter	Type	Description
entity	string	Required, notes, tasks, or events
entity_id	string	Required, the item's UUID

Returns: the restored item as JSON.

create_tag (Pro and Ultra)

Create a new tag, or turn an existing auto-suggested tag into a permanent one.

Parameter	Type	Description
tag	string	Required, 1-50 characters (stored lowercase)
category	string	Optional

set_tag_pinned (Pro and Ultra)

Pin or unpin a tag so it sorts to the top of your tag list.

Parameter	Type	Description
tag	string	Required
pinned	bool	Required

Tags containing a / character can't be pinned.

delete_tag (Pro and Ultra)

Remove a tag. Can be brought back with restore_tag.

Parameter	Type	Description
tag	string	Required

restore_tag (Pro and Ultra)

Bring back a deleted tag.

Parameter	Type	Description
tag	string	Required

Input limits

Field	Max length	Used in
title	200 characters	create/update note, task, event
description	2,000 characters	create/update task, event
summary	1,000 characters (hard)	create/update note. Used in your reports, so keep it short
transcript	plan-based: Pro 20,000 / Ultra 50,000	create/update note. Long-form body, not in reports
text	plan-based: Pro 20,000 / Ultra 50,000 (when no audio is sent)	process_note
location	200 characters	create/update event
tags	20 tags	create/update note, task, event
search query	500 characters	search
audio_base64	about 7 MB of audio (the whole request is limited to 10 MB)	process_note

If you exceed a limit, the tool returns an error message like "title too long (max 200 chars, got 250)".

Error handling

Most tools return errors as JSON:

{"error": "description of what went wrong"}

Plan, scope and input-limit errors come back as a tool error with the same message.

Common errors:

Error	When
"This TellDone connection is read-only. Creating and editing needs the Pro or Ultra plan."	Write tool called in read-only mode (Free and Basic, or Pro and Ultra switched to read-only)
"Daily limit reached: the Free plan includes 100 TellDone requests a day..."	Free plan used up its 100 requests for the day
"Daily limit reached (N/M today)"	You created as many items through AI assistants today as your plan allows (process_note, create_note, create_task and create_event each count)
"Notes limit reached (X/Y this month)"	Your plan's monthly note limit is used up
"Invalid note_id format"	Non-UUID string passed as ID
"Note not found"	ID doesn't exist or belongs to another user
"Task not found or already completed"	complete_task on non-existent or already done task
"title too long (max 200 chars, got N)"	Input limit exceeded
"Too many tags (max 20)"	More than 20 tags provided

HTTP-level errors:

Code	Meaning
401	Invalid, revoked or deleted token (disabling MCP deletes your token, and regenerating replaces it)
429	Rate limit exceeded (5 req/s, burst up to 20)

On Free, reaching the 100-requests-a-day limit is reported as a tool error message (not an HTTP code) and resets at midnight in the time zone saved in your account.

Usage examples

All examples use cURL with the MCP JSON-RPC protocol. Replace YOUR_TOKEN with your access token.

Reading data

# Get your profile and stats
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_profile"}}'

# List recent notes (limit 5, from April 2026)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_notes","arguments":{"limit":5,"date_from":"2026-04-01"}}}'

# Search notes (hybrid text + semantic)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"search","arguments":{"query":"project deadline","limit":5}}}'

Writing data (Pro and Ultra)

# Process a note through full AI pipeline (extracts tasks + events)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call",
       "params":{"name":"process_note","arguments":{"text":"Need to buy groceries tomorrow. Meeting with Katie at 3pm at the cafe to discuss the project."}}}'

# Create a task with deadline and reminder
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call",
       "params":{"name":"create_task","arguments":{"title":"Review PR","priority":"high","deadline":"2026-04-15","reminder_at":"2026-04-15T09:00:00Z","tags":"dev"}}}'

# Create a repeating event with reminders and attendees
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":12,"method":"tools/call",
       "params":{"name":"create_event","arguments":{"title":"Team standup","start_at":"2026-04-12T10:00:00Z","reminder_minutes":"15","attendees":"Katie,John","recurrence_rule":"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR","tags":"meeting"}}}'

# Complete a task
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":13,"method":"tools/call",
       "params":{"name":"complete_task","arguments":{"task_id":"<task-uuid>"}}}'

A successful response looks like:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
  }
}

note

Write and update tools return short responses, mostly id, title and status. Delete tools return id and deleted. To get full details (tags, priority, deadline, etc.) after a write, make a follow-up read call like get_tasks or get_note.

Token management

Action	How
View token	iPhone Settings > Integrations > AI Agents (MCP) > For developers (or on the web, Settings > Integrations > AI agents (MCP)), tap Show
Copy token	Tap Copy next to the token
Regenerate	Tap Regenerate Token and confirm. The old token stops working immediately. Assistants connected with OAuth sign-in are not affected; disconnect them under Connected apps
Change mode	Pro and Ultra: choose Read-only or Read & Write. Free and Basic are always Read-only
Disable	Tap Disable and confirm ("This will revoke access for all connected AI tools."). Your token is deleted and all connections stop. If you enable MCP again, you get a new token, and apps connected with sign-in (OAuth) work again without signing in. To remove an app for good, tap Disconnect under Connected apps

What you can ask your AI agent

Once connected, ask your AI tool things like:

Review your day:

• "What did I work on today?"
• "Show me my notes from this week"
• "What tasks are overdue?"

Manage tasks:

• "Create a task: review quarterly report, high priority, deadline Friday"
• "Mark the Figma task as done"
• "What tasks am I working on?"

Search and analyze:

• "Find all notes about the marketing strategy"
• "What events do I have next week?"
• "Summarize my daily reports from last week"

Plan ahead:

• "Create an event: team standup tomorrow at 10am"
• "What's on my calendar this week?"
• "Show me my top tags - what do I spend most time on?"

Your assistant can read your notes, tasks, events, and reports, and answer complex questions by combining information from several tools. On Pro and Ultra with Read & Write on, it can also create, update, and delete them.

Good to know

• Integrations and automations - process_note works like a recording, so its note, tasks and events go to your connected integrations and webhook automations. Items you create, edit or delete with the other write tools appear in your TellDone apps right away but are not sent to Todoist, Notion, Microsoft To Do or your automations. One exception: restoring a task with restore_entity, or undoing its completion with undo_change_log_entry, also reopens it in the integrations it was synced to.
• Semantic search - notes created with process_note or create_note both get embeddings, so they show up in semantic search after a short delay.
• Date filters - for notes, dates are UTC days. For events, dates are your own local days, and an event that overlaps the range is included. For tasks, the filter is the deadline date.

Security

• Each user gets a unique 384-bit access token
• Your token is revoked instantly when you disable MCP or regenerate it
• Every request is scoped to your account, so your agent can only access your own data
• Connection uses HTTPS with rate limiting (5 req/s, burst up to 20)
• OAuth connections use PKCE with single-use authorization codes and short-lived access tokens - you can revoke a connection at any time from the app

For a technical deep-dive - discovery endpoints, token lifetimes, the full OAuth flow - see our open-source connector reference at github.com/exp78/telldone-mcp, or query https://api.telldone.app/.well-known/oauth-protected-resource directly.

Privacy and data flow

A connected AI tool gets your data only when it calls TellDone, usually because you asked it something. It receives only the answers to those calls, within the permissions you approved. To limit access, switch to Read-only, disconnect the app under Connected apps, or regenerate or disable your access token in Settings. See the Privacy Policy for full details, or reach out to support@telldone.app with questions.

Troubleshooting

Symptom	Cause / fix
OAuth consent page says "Wrong email or password"	Use the email and password you sign into the app with, or choose Sign in with Apple / Sign in with Google on the same page.
Connected, but the AI can't create or edit anything	Your plan is Free or Basic (read-only), your mode is read-only, or the connection doesn't have write permissions. If you connected before you upgraded, disconnect the app under Connected apps and connect it again. You can check your mode in Settings.
"Insufficient scope" error from a tool	The connection doesn't have that permission. On Free and Basic, write permissions are never granted, so creating and editing needs Pro or Ultra. If you connected before you upgraded, disconnect the app under Connected apps and connect it again.
The copied snippet says YOUR_TOKEN and the client can't connect	You copied it while the token was hidden. In For developers, tap Show, then copy the snippet again.
Tools don't appear at all	MCP isn't enabled on your account (Settings > Integrations > AI Agents (MCP) > Enable).
"Daily limit reached"	Two limits use this message. "Daily limit reached: the Free plan includes 100 TellDone requests a day" is Free's request limit. "Daily limit reached (N/M today)" means you have created as many items through AI assistants today as your plan allows: process_note, create_note, create_task and create_event each count, on Pro and Ultra too. Both reset at midnight in the time zone saved in your account.
My client only lets me pick from a list of connectors, and TellDone isn't on it	TellDone isn't in any client's connector directory yet - add it as a custom connector with the MCP URL, or use the bearer-token method.

See also

• Webhook automations - send data to external services automatically
• Todoist - dedicated two-way task sync
• Notion - dedicated Notion integration