← telldone.ai

Connect an AI agent to TellDone

TellDone exposes an MCP server. Once a user connects it, an assistant can read and manage their notes, tasks, events, reports, and tags on their behalf.

Machine-readable: connect.json · tools.json · Markdown version. Full user docs: docs.telldone.app.

At a glance

Tools	27: 10 read, 17 write
Plans	Pro and Ultra, both with read and write (either can switch to read-only). Ultra has higher quotas. Free and Basic have no MCP access.
Transport	Streamable HTTP, stateless. Send `Accept: application/json`.
Server URL (OAuth)	`https://api.telldone.app/mcp/user`
Server URL (token)	`https://api.telldone.app/mcp/user/mcp`
Auth	OAuth 2.1 (PKCE S256, dynamic client registration), or a personal bearer token
Rate limit	5 requests per second; excess requests get HTTP 429

Before you connect

The user needs a Pro or Ultra plan.
They turn MCP on in the app: Settings → Integrations → AI Agents on iPhone, or Settings → AI Agents at app.telldone.app.
For the token method, they copy the token from that screen. They can regenerate or disable it at any time, which drops all connections.

Authentication

OAuth 2.1 (recommended). Clients discover everything from the server. An unauthenticated request to https://api.telldone.app/mcp/user returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata. Clients register themselves (RFC 7591), so any MCP client that supports remote OAuth servers can connect without pre-approval. The sign-in page offers Sign in with Apple, Sign in with Google, and email and password, so every TellDone account can connect this way.

Protected resource metadata	/.well-known/oauth-protected-resource
Authorization server metadata	/.well-known/oauth-authorization-server
Endpoints	`/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/revoke`, `/oauth/userinfo` on `api.telldone.app`
Scopes	`notes:read` `notes:write` `tasks:read` `tasks:write` `events:read` `events:write` `reports:read` `tags:read` `tags:write` `profile:read` `offline_access`

Scopes are a ceiling: a token without a write scope cannot call a write tool. The plan and the user's read/write mode are a second gate. offline_access issues a refresh token so the connection survives between sessions.

Bearer token. Send Authorization: Bearer YOUR_TOKEN to https://api.telldone.app/mcp/user/mcp. If a proxy reserves the Authorization header, X-MCP-Token: YOUR_TOKEN works the same way. Token connections are not scoped; the plan and read/write mode govern them.

Setup by client

Claude (claude.ai and Claude Desktop)

Add a custom connector, enter the URL below, sign in with TellDone, and click Allow. No token to copy.

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

Claude Code

OAuth:

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

Then run /mcp inside Claude Code and choose Authenticate to open the browser sign-in. Or, with a token and no browser:

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, as given in TellDone's docs:

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

OpenClaw

Settings → MCP Servers → Add, then fill in:

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

Any other MCP client

Clients with remote OAuth support: use https://api.telldone.app/mcp/user and complete the sign-in. Clients that take a header: use https://api.telldone.app/mcp/user/mcp with the bearer token.

Authorization: Bearer YOUR_TOKEN

Check a token from the command line:

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}'

Read tools (10)

`get_profile`	Account info, plan, effective MCP mode, locale, timezone, and counts of notes, tasks and events.
`get_notes`	List notes, newest first, with filters.
`get_note`	One note with its linked tasks, events and full transcript.
`get_notes_full`	Several notes with embedded tasks and events in one call.
`get_tasks`	List tasks.
`get_events`	List calendar events by date range.
`get_change_log`	Edit history of a note, task or event, newest first, with whether each edit was undone.
`get_reports`	Generated daily, weekly, monthly or yearly reports as markdown.
`get_tags`	The user's tags, pinned first, then by usage. Up to 100.
`search`	Search notes, tasks and events. Notes also get semantic (by meaning) matching.

Write tools (17)

`process_note`	Run text or audio through the full TellDone pipeline (transcription, structuring). Asynchronous: returns an audio_id with status processing; poll get_notes for the result. Counts against plan quotas.
`create_note`	Create a plain text note instantly, with no AI analysis.
`create_task`	Create a task.
`create_event`	Create a calendar event.
`update_note`	Update note fields. Only fields you pass change.
`update_task`	Update task fields. Only fields you pass change.
`complete_task`	Mark a task as done.
`update_event`	Update event fields. Only fields you pass change.
`delete_note`	Soft-delete a note and its linked tasks and events. Reversible with restore_entity.
`delete_task`	Soft-delete a task. Reversible with restore_entity.
`delete_event`	Soft-delete an event. Reversible with restore_entity.
`undo_change_log_entry`	Undo one tracked edit (AI-made or manual), restoring the field's earlier value.
`restore_entity`	Restore a deleted or archived note, task or event.
`create_tag`	Create a manual tag, or turn an auto-tag into a manual one.
`set_tag_pinned`	Pin or unpin a tag.
`delete_tag`	Soft-delete a tag. Reversible with restore_tag.
`restore_tag`	Restore a deleted tag.

Parameters and required OAuth scope for each tool are in tools.json.

Behavior to know

Every tool returns a JSON string in content[0].text. A failure is {"error": "..."}, so check for that key.
Timestamps are ISO 8601 strings and dates are YYYY-MM-DD.
Create and update tools return a minimal record (id, title, status). Call a read tool for full fields.
process_note is asynchronous. Processing takes 10 to 30 seconds; poll get_notes for the result.
Deletes are soft. restore_entity brings an item back, and undo_change_log_entry reverses a single edit.
Changes appear on the user's phone and web app through real-time sync.
Data goes to a connected tool only when the user asks it to read or change something. See the privacy policy.

Help: support@telldone.app