# Connect an AI agent to TellDone (MCP)

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](/mcp/connect.json), [tools.json](/mcp/tools.json). User docs: https://docs.telldone.app/integrations/mcp-access
## At a glance

- Tools: 27 (10 read, 17 write)
- Plans: Pro and Ultra, both 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

1. The user needs a Pro or Ultra plan.
2. They turn MCP on in the app: Settings > Integrations > AI Agents (iPhone) or Settings > AI Agents at https://app.telldone.app.
3. For the token method, they copy the token from that screen. They can regenerate or disable it at any time.

## Authentication

OAuth 2.1 (recommended). 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 with remote OAuth support can connect. 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: https://api.telldone.app/.well-known/oauth-protected-resource
- Authorization server metadata: https://api.telldone.app/.well-known/oauth-authorization-server
- Endpoints on api.telldone.app: `/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/revoke`, `/oauth/userinfo`
- 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.

Bearer token: send `Authorization: Bearer YOUR_TOKEN` to `https://api.telldone.app/mcp/user/mcp`. If a proxy reserves Authorization, `X-MCP-Token: YOUR_TOKEN` works the same way. Token connections are not scoped.

## Setup by client

### Claude (claude.ai and Claude Desktop)

Add a custom connector, enter `https://api.telldone.app/mcp/user`, sign in with TellDone, click Allow.

### Claude Code

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

Then run `/mcp` in Claude Code and choose Authenticate. With a token instead:

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

### Cursor (`.cursor/mcp.json`)

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

### Windsurf (`.codeium/windsurf/mcp_config.json`)

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

### Codex (`codex.json`, as given in TellDone's docs)

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

### Any other MCP client

Remote OAuth support: use `https://api.telldone.app/mcp/user` and complete the sign-in. Header-based: use `https://api.telldone.app/mcp/user/mcp` with `Authorization: Bearer YOUR_TOKEN`.

```bash
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 OAuth scopes per tool: /mcp/tools.json

## Behavior to know

- Every tool returns a JSON string in `content[0].text`. A failure is `{"error": "..."}`.
- Timestamps are ISO 8601 strings; 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`.
- Deletes are soft. `restore_entity` brings an item back; `undo_change_log_entry` reverses one 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. Privacy policy: https://telldone.app/privacy

Help: support@telldone.app