TellDone

Connect yourTellDonevoice notes, tasks, events, and reports toClaude(Desktop, claude.ai, and Code), Cursor, Windsurf, Codex, and any MCP-compatible client — withone-click OAuth(browser sign-in, no token to copy) or a bearer token.

claude mcp add --transport http telldone https://api.telldone.app/mcp/user

First get a token: sign up atapp.telldone.app, openSettings → AI Agents (MCP), and clickEnable. Then add the server with your token:

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

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

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

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

Every tool returns JSON. The MCP wire response wraps payloads inresult.content[0].textas aJSON-encoded string— parse it withjson.loads()(or equivalent) to get the actual data.

All datetimes, dates, and UUIDs in the decoded JSON are STRINGS, not native language types.Do not call.toordinal(),.weekday(), or any datetime method directly on them — you will getTypeError: 'str' has no attribute 'toordinal'. Parse them first.

- priority—"low","medium","high", ornull
- note.type—"task","idea","info","status","meeting","event","reflection"
- note.status—"active","archived"(deleted records are excluded from every read tool)
- task.status—"todo","done"(query paramstatus="all"means "all not-deleted")
- event.status—"confirmed","tentative","cancelled"
- report.type—"daily","weekly","monthly","yearly"
- source(tasks),completed_by(tasks) — free-form strings:"mcp","app","sync","audio","todoist","notion", etc.

- note_id,task_id,event_id,parent_*_id— UUID strings
- date_from,date_to,deadline—YYYY-MM-DDstrings (empty string means "no filter")
- start_at,end_at,reminder_at— ISO 8601 datetime strings, e.g."2026-04-15T09:00:00Z"or"2026-04-15T09:00:00+00:00"
- tags— comma-separated string on input (e.g."work,urgent"); stored/returned asstring[]
- reminder_minutes,attendees— comma-separated strings on input; stored/returned as arrays
- is_all_day— boolean oncreate_event; string"true"/"false"onupdate_event
- recurrence_rule— RRULE string, e.g."FREQ=WEEKLY;BYDAY=MO,WE,FR"

import json from datetime import datetime, date # tools/call response → text → decode payload = json.loads(response["result"]["content"][0]["text"]) # Check for error first if "error" in payload: raise RuntimeError(payload["error"]) # Events: start_at is a STRING like "2026-04-18T11:30:00+00:00" for e in payload: # payload is list from get_events start = datetime.fromisoformat(e["start_at"]) # -> tz-aware datetime if e["end_at"]: end = datetime.fromisoformat(e["end_at"]) # Tasks: deadline is a STRING like "2026-04-18" (date only) for t in tasks_payload: if t["deadline"]: d = date.fromisoformat(t["deadline"]) days_left = (d - date.today()).days

Every note has three text fields withdifferent roles and different limits. Choosing the right field matters — LLM clients (Claude Desktop, Cursor, etc.) should split content appropriately when usingcreate_noteorupdate_note.

Plan-based transcript limits(subscription_plans.max_text_length):

- Short output (notes, reminders, todos):justtitle+summary. Leavetranscriptempty.
- Long output (meeting notes, drafts, brainstorms, research dumps):put a 1–3 sentencesummaryand thefull body intranscript. Do not pack everything into summary — you'll hit the 1000-char error.

- summary too long (max 1000 chars, got N). For long-form content use the 'transcript' parameter (plan-based limit).
- transcript too long (max 20000 chars for pro plan, got N)

Correct usage example(Claude Desktop captures a meeting):

create_note({ title: "Weekly engineering sync — API versioning", summary: "Team agreed on semver deprecation policy with 6-month sunset window. Owner: Alex. Next sync: Thu.", transcript: "Full meeting transcript: Alice raised the question of how to deprecate v1...\n\n[... 5 KB of detail ...]", tags: "engineering,versioning,meeting" })

- summaryis includedverbatimin daily/weekly/monthly report LLM prompts. If every summary could be 20 KB, report prompts would blow up in cost and latency (and risk context-window overflow for heavy users). 1000 chars was set in April 2026 after measuring prod data (median 247, max 554).
- transcriptisneverin report prompts — it only shows up in the UI detail view. Large transcripts cost only storage, not LLM tokens. Capping by plan prevents abuse but otherwise lets you be generous.

Backward compatibility:transcriptis an optional parameter (default""). Old clients callingcreate_note(title, summary, tags, type)continue to work unchanged — the database storestranscript = NULL. No migration needed.

All tools includeMCP annotations—title,readOnlyHint,destructiveHint,idempotentHint,openWorldHint— so MCP clients can surface the right confirmation UI. Every tool runs against the Telldone database only (openWorldHint: false) — the server never reaches out to external APIs.

Text or Audio --> STT (if audio) --> LLM Analysis --> Note + Tasks + Events + Tags

{"name": "process_note", "arguments": {"text": "Need to buy groceries. Meeting with Katie at 3pm."}}

{"name": "process_note", "arguments": {"audio_base64": "...", "audio_format": "m4a"}}

#!/bin/bash # Test your TellDone MCP connection TOKEN="${1:?Usage: ./test-connection.sh YOUR_TOKEN}" URL="https://api.telldone.app/mcp/user/mcp" echo "=== Testing connection ===" curl -s -X POST "$URL" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_profile"}}' \ | python3 -m json.tool echo "" echo "=== Listing tools ===" curl -s -X POST "$URL" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \ | python3 -c "import sys,json; tools=json.load(sys.stdin).get('result',{}).get('tools',[]); print(f'{len(tools)} tools available'); [print(f' {t[\"name\"]}') for t in tools]"

#!/bin/bash # Get today's tasks and notes summary TOKEN="${1:?Usage: ./daily-summary.sh YOUR_TOKEN}" URL="https://api.telldone.app/mcp/user/mcp" TODAY=$(date +%Y-%m-%d) call() { curl -s -X POST "$URL" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d "$1" } echo "=== Today's Notes ($TODAY) ===" call "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"get_notes\",\"arguments\":{\"date_from\":\"$TODAY\",\"limit\":20}}}" \ | python3 -c " import sys, json r = json.loads(json.load(sys.stdin)['result']['content'][0]['text']) for n in r: print(f' [{n[\"type\"]}] {n[\"title\"]}')" 2>/dev/null echo "" echo "=== Active Tasks ===" call '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_tasks","arguments":{"status":"todo","limit":10}}}' \ | python3 -c " import sys, json r = json.loads(json.load(sys.stdin)['result']['content'][0]['text']) for t in r: print(f' [{t[\"priority\"]}] {t[\"title\"]}')" 2>/dev/null echo "" echo "=== Upcoming Events ===" call "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"get_events\",\"arguments\":{\"date_from\":\"$TODAY\",\"limit\":5}}}" \ | python3 -c " import sys, json r = json.loads(json.load(sys.stdin)['result']['content'][0]['text']) # NOTE: start_at is a STRING like '2026-04-18T11:30:00+00:00' — parse before date math for e in r: print(f' {e[\"start_at\"][:16]} {e[\"title\"]}')" 2>/dev/null

#!/bin/bash # Create a task via MCP TOKEN="${1:?Usage: ./create-task.sh YOUR_TOKEN 'Task title'}" TITLE="${2:?Usage: ./create-task.sh YOUR_TOKEN 'Task title'}" PRIORITY="${3:-medium}" curl -s -X POST "https://api.telldone.app/mcp/user/mcp" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"create_task\",\"arguments\":{\"title\":\"$TITLE\",\"priority\":\"$PRIORITY\"}}}" \ | python3 -m json.tool

Pro and Ultra have the same MCP tools. Ultra has higher quotas (unlimited notes, 1500 STT min/mo, 300 uploads/day).

TellDone supports two ways to connect — pick one.

One-click browser sign-in, nothing to copy or store. Standards-compliant: OAuth 2.1 with PKCE (S256), authorization-server + protected-resource discovery (RFC 8414 / RFC 9728), audience-bound access tokens (RFC 8707), rotating refresh tokens, and Client ID Metadata Documents (so Claude Desktop / claude.ai connect with no manual registration). Access isscoped— you approve exactly what the app may do on the consent screen, and read-only vs read & write follows your plan. Revoke any time inSettings → AI Agentsor by disabling MCP.

- Connector URL:https://api.telldone.app/mcp/user
- Discovery:https://api.telldone.app/.well-known/oauth-protected-resource
- Scopes:notes:read·notes:write·tasks:read·tasks:write·events:read·events:write·reports:read·tags:read·tags:write·profile:read·offline_access

For clients without OAuth. Generate a long-lived token in the web app —Settings → AI Agents (MCP) → Enable— and send it asAuthorization: Bearer <token>.

- Endpoint URL:https://api.telldone.app/mcp/user/mcp
- Regenerate: Settings → AI Agents → Regenerate (old token revoked instantly)
- Disable: Settings → AI Agents → Disable (token deleted)

MCP Streamable HTTP (stateless). Each request is independent.

POST https://api.telldone.app/mcp/user/mcp Authorization: Bearer <token> Content-Type: application/json Accept: application/json

- App:app.telldone.app
- Website:telldone.app
- Docs:docs.telldone.app
- iOS App:App Store

Connect your Amazing Marvin productivity system with AI assistants for smarter task management.