TellDone MCP Server

Connect your TellDone voice notes, tasks, events, and reports to Claude (Desktop, claude.ai, and Code), Cursor, Windsurf, Codex, and any MCP-compatible client — with one-click OAuth (browser sign-in, no token to copy) or a bearer token.

TellDone is a voice-first planning app. Dictate your thoughts, and AI automatically creates structured notes, tasks, events, and daily productivity reports.

Voice recording is available on iOS and Apple Watch. Android coming soon. You can also send text through MCP using `process_note` for the same AI analysis pipeline.

> Use promo code `MCPBETA26` after signup to get free MCP access (read & write for 30 days, then read-only for a year).

Quick Start

Connect in one of two ways: one-click OAuth (recommended — browser sign-in, nothing to copy) or a bearer token (works with every MCP client).

Option A — One-click OAuth · Claude Desktop, claude.ai, Claude Code

Add TellDone as a connector, sign in to your account in the browser, and approve. Access tokens are short-lived, scope-limited, and revocable any time in Settings — there's nothing to copy or store.

Claude Desktop & claude.ai — in Settings, open Connectors, choose Add custom connector, and paste:

https://api.telldone.app/mcp/user

Click Connect, sign in to TellDone, and approve the access. No manual app registration — TellDone supports Client ID Metadata Documents, so Claude registers itself automatically.

Claude Code

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

Then run `/mcp` and choose telldone → Authenticate to open the TellDone consent page in your browser — sign in and approve once. (CLI v2.1.186+: `claude mcp login telldone` does the same from the shell.)

> Any MCP client that supports OAuth 2.1 discovery (RFC 9728 + RFC 8414) connects the same way.

Option B — Bearer token · Cursor, Windsurf, Codex, or any client

First get a token: sign up at app.telldone.app, open Settings → AI Agents (MCP), and click Enable. Then add the server with your token:

Claude Code

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

Cursor `.cursor/mcp.json`

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

Windsurf `.codeium/windsurf/mcp_config.json`

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

Codex `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`

Start Using

Ask your AI tool things like:

• *"What did I work on today?"*
• *"Create a task: review quarterly report, high priority, deadline Friday"*
• *"Find all notes about the marketing strategy"*
• *"Mark the Figma task as done"*
• *"Create an event: team standup tomorrow at 10am, remind me 15 min before"*
• *"Process this meeting summary and extract tasks"*
• *"What events do I have next week?"*
• *"Show me my daily report from yesterday"*

Data Formats — Read This Before Parsing Output

Every tool returns JSON. The MCP wire response wraps payloads in `result.content[0].text` as a JSON-encoded string — parse it with `json.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 get `TypeError: 'str' has no attribute 'toordinal'`. Parse them first.

Scalar output types

Array / object output types

Enum values

• `priority` — `"low"`, `"medium"`, `"high"`, or `null`
• `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 param `status="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.

Per-tool output fields

Input parameter formats

• `note_id`, `task_id`, `event_id`, `parent_*_id` — UUID strings
• `date_from`, `date_to`, `deadline` — `YYYY-MM-DD` strings (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 as `string[]`
• `reminder_minutes`, `attendees` — comma-separated strings on input; stored/returned as arrays
• `is_all_day` — boolean on `create_event`; string `"true"`/`"false"` on `update_event`
• `recurrence_rule` — RRULE string, e.g. `"FREQ=WEEKLY;BYDAY=MO,WE,FR"`

Parsing example (Python)

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

Note Fields: title, summary, transcript

Every note has three text fields with different roles and different limits. Choosing the right field matters — LLM clients (Claude Desktop, Cursor, etc.) should split content appropriately when using `create_note` or `update_note`.

Plan-based transcript limits (`subscription_plans.max_text_length`):

Rule of thumb for LLM clients:

• Short output (notes, reminders, todos): just `title` + `summary`. Leave `transcript` empty.
• Long output (meeting notes, drafts, brainstorms, research dumps): put a 1–3 sentence `summary` and the full body in `transcript`. Do not pack everything into summary — you'll hit the 1000-char error.

Overflow error messages:

• `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"
})

Why two different caps?

• `summary` is included verbatim in 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).
• `transcript` is never in 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: `transcript` is an optional parameter (default `""`). Old clients calling `create_note(title, summary, tags, type)` continue to work unchanged — the database stores `transcript = NULL`. No migration needed.

Tools (20)

All tools include MCP 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.

Read Tools (9)

Write Tools (11)

All write tools sync in real-time to connected mobile and web clients via WebSocket.

Full Pipeline: `process_note`

The `process_note` tool runs the same pipeline as recording in the mobile app:

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

Text mode (skip STT):

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

Audio mode (base64-encoded):

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

Returns immediately with `audio_id`. Results arrive via WebSocket or poll with `get_notes()`.

Examples

`examples/test-connection.sh`

#!/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]"

`examples/daily-summary.sh`

#!/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

`examples/create-task.sh`

#!/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

Plans and Access

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

Authentication

TellDone supports two ways to connect — pick one.

OAuth 2.1 (recommended)

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 is scoped — you approve exactly what the app may do on the consent screen, and read-only vs read & write follows your plan. Revoke any time in Settings → AI Agents or 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`

Bearer token

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

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

Rate limit (both): 5 requests/second.

Transport

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

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

Links

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