MCP Access (AI agents)

Pro plan and above

MCP Access requires a Pro or Ultra plan. Both plans get full read + write access (20 tools). Ultra has higher quotas.

MCP (Model Context Protocol) lets you connect AI coding assistants and automation tools directly to your TellDone data. Once connected, your AI agent can read your notes, tasks, events, and reports - and create, update, and delete items. There are 20 tools total: 9 for reading data and 11 for writing.

Plan requirements

Feature	Free	Basic	Pro	Ultra
MCP Access	-	-	Read + Write (20 tools)	Read + Write (20 tools, higher quotas)

How to enable

MCP is currently configured only in the web app at app.telldone.app (not available in the iOS app yet):

1. Go to Settings > Integrations > AI Agents (MCP)
2. Click Enable
3. Choose your access mode:
   • Read-only - the agent can view your data but not modify it
   • Read + Write - the agent can also create, update, and delete items
4. Copy your connection token - you will need it to connect your AI tool

tip

Keep your connection token private. Anyone with the token can access your TellDone data. You can regenerate it at any time from the same settings page.

Connecting your AI tool

Claude Code

Run this command in your terminal:

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

Cursor

Add to .cursor/mcp.json:

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

Windsurf

Add to .codeium/windsurf/mcp_config.json:

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

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.

Replace YOUR_TOKEN with the token from your settings in all examples above.

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.

What you can do

Read tools (9) - Pro and Ultra

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 usage stats
search	Search across notes, tasks, and events (text + semantic search for notes)

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 (11) - 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 recurrence
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, recurrence, 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

All write and delete operations appear instantly on your connected devices (phone, web app) via real-time sync.

Tools reference

get_notes

List notes with optional filtering. Date filters use recorded_at (when you recorded the voice note), not created_at.

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)

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.

get_notes_full

Get multiple notes with their tasks and events in a single call. Same filters as get_notes, but 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

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 (by created_at)
date_to	string	-	End date, YYYY-MM-DD

Returns: list of tasks with id, title, description, status, priority, tags, deadline, reminder_at, completed_at, completed_by, source, created_at.

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	-	Start date, YYYY-MM-DD (filters by event start time)
date_to	string	-	End date, YYYY-MM-DD

Returns: list of events with id, title, description, status, start_at, end_at, location, is_all_day, tags, 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 can be 3,000-5,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 usage statistics.

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.

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	Text to analyze (skips transcription if no audio provided)
audio_base64	string	Base64-encoded audio file (up to 50MB, triggers transcription)
audio_format	string	m4a, ogg, wav, or mp3 (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

You must provide either text or audio_base64 (or both - audio takes priority for transcription).

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). Use get_profile to check your current usage.

create_note (Pro and Ultra)

Create a plain text note instantly. Does not trigger AI analysis - no tasks or events are extracted. For full AI analysis with task/event extraction, use process_note instead.

Parameter	Type	Limit	Description
title	string	200 chars	Required
summary	string	1000 chars	Optional
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 (e.g. 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)
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 (e.g. 15,60), optional
attendees	string	-	Comma-separated names or emails, optional
recurrence_rule	string	-	RRULE string (e.g. FREQ=WEEKLY;BYDAY=MO,WE,FR), optional
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. The transcript is not editable (it's the source of truth from speech-to-text).

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)
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

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 (pass a space to clear)
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 (e.g. 15,60)
attendees	string	Comma-separated names or emails
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

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	create/update note
location	200 characters	create/update event
tags	20 tags	create/update note, task, event
search query	500 characters	search

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

Error handling

All tools return JSON. Errors use this format:

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

Common errors:

Error	When
"MCP access is read-only..."	Write tool called with read-only mode
"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 or missing Bearer token
403	MCP disabled or plan doesn't allow MCP
429	Rate limit exceeded (5 req/s)

Usage examples

All examples use cURL with the MCP JSON-RPC protocol. Replace YOUR_TOKEN with your connection 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 recurring 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": 10,
  "result": {
    "content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
  }
}

note

Write and update tools return minimal responses with only id, title, and status. 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	Settings > Integrations > AI Agents > eye icon
Copy token	Click the copy icon next to the token
Regenerate	Click "Regenerate" and confirm. The old token stops working immediately
Change mode	Toggle between Read-only and Read + Write
Disable	Click "Disable" and confirm. Token is deleted, all connections stop

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?"

The AI agent has full access to your notes, tasks, events, and reports. It can read, create, update, and delete data, and answer complex questions by combining information from multiple tools.

Important notes

• Two ways to create notes - create_note creates a plain text note instantly (no AI analysis). process_note runs the full AI pipeline (same as recording in the app) - it analyzes the text, extracts tasks and events, generates tags and embeddings. Use process_note when you want TellDone to do the thinking for you.
• No integration sync - items created or updated via MCP don't trigger webhook automations or integration syncs (Todoist, Notion). They will appear in your apps on the next sync.
• Semantic search depends on the tool - notes created with process_note get embeddings and appear in semantic search. Notes created with create_note do not get embeddings, so they only appear in text search.
• Write responses are minimal - create and update tools return only id, title, and status. To get all fields after a write, make a follow-up read call.
• Date filters use UTC - date_from/date_to parameters are compared as UTC timestamps. For users in non-UTC timezones, boundary dates may include or exclude items from adjacent days.
• Rate limit - 5 requests per second. For bulk operations, pace your requests.

Security

• Each user gets a unique 384-bit connection token
• Your token is revoked instantly when you disable MCP or regenerate it
• All data is strictly isolated to your account - your agent can only access your own data
• Every request is scoped to your user - there is no way for an agent to access another user's data
• Connection uses HTTPS with rate limiting (5 req/s)

See also

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