MCP 访问（AI agents）

连接的两种方式

有两种方式可以验证 AI 客户端的身份，两种都完全支持：

OAuth 2.1（推荐） - 标准的「使用 TellDone 登录」授权流程。Claude Desktop 的连接器界面和 Claude.ai 用的就是这种方式。无需复制令牌 - 你用 TellDone 账户登录，并批准客户端请求的权限。
Bearer 令牌 - 从设置中复制你的个人访问令牌，粘贴到客户端配置里。对脚本、命令行工具，以及没有内置 OAuth 流程的客户端来说最简单。

客户端	推荐方式
Claude Desktop / Cowork	OAuth - 用 MCP URL 添加自定义连接器，然后登录
Claude Code（CLI）	两种均可 - `claude mcp add` 会引导你在浏览器中完成 OAuth，或者为令牌方式添加 `Bearer` 头
脚本或你自己的代码	Bearer 令牌 - 最容易自动化
只支持从已列出的连接器目录中选择的客户端	目前请使用 Bearer 令牌或 `mcp-remote` 桥接 - TellDone 尚未进入任何连接器目录

套餐要求

套餐	MCP
Free	锁定
Basic	锁定
Pro	读 + 写（27 个工具） - 可切换到只读模式
Ultra	读 + 写（27 个工具） - 可切换到只读模式

应用内屏幕

AI Agents 屏幕根据你的套餐和 MCP 是否打开有三种状态。

锁定（Free 和 Basic）

如果你在 Free 或 Basic 套餐上，屏幕会说明 MCP 的功能并显示升级按钮。点按它会打开付费墙，让你升级到 Pro 或 Ultra。

已禁用（Pro 和 Ultra，功能未开）

如果你在 Pro 或 Ultra 上但还没有打开 MCP，屏幕会显示你套餐能做什么的简短摘要（工具数量、访问模式、配额）和一个启用按钮。点按它生成你的连接令牌并启动集成。

已启用

启用后，屏幕显示连接 AI 客户端所需的一切：

模式开关 - 在 Ultra 上你可以在只读和读 + 写之间切换。在 Pro 上模式固定为读 + 写。
访问令牌行带有眼睛图标用于显示或隐藏令牌，并有复制按钮。
设置选择器带有 Claude Code、Cursor、Windsurf 和其他标签页。匹配的代码片段出现在标签页下方 - 复制粘贴到你的 AI 客户端即可。
重新生成按钮 - 立即轮换令牌，并断开使用旧令牌的所有活动会话。
禁用按钮 - 关闭 MCP 并删除令牌。你可以稍后重新启用，但会签发新令牌。

提示

请将连接令牌保密。任何拥有令牌的人都可以访问你的 TellDone 数据。如果你怀疑令牌泄露，请使用重新生成。

如何启用

你可以从任一平台配置 MCP：

iPhone： 设置 → 集成 → AI Agents（MCP）
网页： app.telldone.app → 设置 → AI Agents

步骤：

点按启用。
选择你的访问模式（仅 Ultra - Pro 始终为读 + 写）。
用眼睛和复制图标显示并复制你的令牌。
在设置部分选择你的工具（Claude Code、Cursor、Windsurf 或其他）。
把代码片段粘贴到你的 AI 客户端配置中。

使用 OAuth 连接

对 Claude Desktop、Claude.ai、Cowork 和 Claude Code 来说，OAuth 是推荐的方式 - 你用 TellDone 账户登录，而不用到处复制令牌。

用于 OAuth 的 MCP URL： https://api.telldone.app/mcp/user（末尾没有 /mcp - 那是另一个 URL，只用于下面的 Bearer 令牌方式）

Claude Desktop / Cowork

在客户端中选择添加自定义连接器。
输入服务器 URL：https://api.telldone.app/mcp/user
客户端会在浏览器中打开 TellDone 的授权页面。你会看到哪个应用在请求访问、它想要的具体权限，以及一个登录表单。
用你的 TellDone 账户邮箱和密码登录，然后点击允许。
客户端会自动收到访问令牌并完成连接 - 无需复制任何令牌。

备注

授权页面上的登录使用你的 TellDone 账户邮箱和密码。如果你的账户只用 Apple 或 Google 登录（没有设置密码），目前请使用下面的 Bearer 令牌方式。

Claude Code

OAuth（会打开浏览器登录）：

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

Claude Code 会自动发现 OAuth 流程，但首次调用时不会帮你登录 - 在 Claude Code 中运行 /mcp 并选择 Authenticate，即可打开浏览器登录。之后它会自动为你刷新访问令牌，无需再维护。

Bearer 令牌（不用浏览器，适合无界面环境）：

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

你的 YOUR_TOKEN 可以在应用中获取：设置 → 集成 → AI Agents → 复制令牌（参见上面的如何启用）。

使用 Bearer 令牌连接

对于没有内置 OAuth 支持的客户端 - Cursor、Windsurf 等 - 请把你的个人访问令牌直接粘贴到客户端配置中。下面所有示例中把 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

设置 > MCP Servers > 添加：

名称：TellDone
URL：https://api.telldone.app/mcp/user/mcp
认证：Bearer YOUR_TOKEN

其他 MCP 客户端

任何支持 HTTP 上 MCP 的工具都可以连接。使用端点 https://api.telldone.app/mcp/user/mcp 并带 Bearer YOUR_TOKEN 授权头。

替代认证头

如果你的客户端或代理保留了 Authorization 头（例如某些 Smithery 风格的网关），请改用 X-MCP-Token: YOUR_TOKEN 发送令牌。两个头都可用；如果同时存在，Authorization 优先。

测试你的连接

你可以用一条简单的 cURL 命令验证你的令牌是否生效：

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

成功的响应会列出所有可用工具。

权限（scopes）

OAuth 连接是有权限范围的 - 登录时你会看到客户端具体请求了什么，并明确批准它。

Scope	允许应用…
`notes:read`	读取你的笔记、搜索、打开笔记完整详情
`notes:write`	创建、编辑、删除笔记（以及运行语音笔记流水线）
`tasks:read` / `tasks:write`	读取 / 创建、编辑、完成和删除任务
`events:read` / `events:write`	读取 / 创建、编辑和删除事件
`reports:read`	读取你的每日、每周、每月和每年报告
`tags:read` / `tags:write`	列出你的标签 / 创建和重命名标签
`profile:read`	读取你的资料和订阅信息
`offline_access`	在你离开时保持连接（签发刷新令牌，这样你不必每次会话都登录）

Scope 是上限，不是保证 - 只有 notes:read 的连接无论你怎么要求都无法调用写工具。你的套餐是 scope 之上的第二道关卡。

Bearer 令牌连接不单独设置 scope - 它们只受你套餐的读/写模式约束。

你能做什么

读工具（10） - Pro 和 Ultra

工具	作用
get_notes	列出笔记，支持筛选（标签、日期范围、文本搜索）
get_note	查看单条笔记，包括子任务、事件和完整转录文本
get_notes_full	一次调用获取多条笔记，附带嵌入的任务和事件
get_tasks	按状态（待办、已完成、全部）、标签或日期筛选任务
get_events	列出日历事件，按日期范围筛选
get_reports	读取你的每日、每周、每月和每年报告（完整 markdown）
get_tags	查看你所有标签，按使用情况排序
get_profile	查看你的账户信息和使用统计
search	跨笔记、任务和事件搜索（笔记支持文本 + 语义搜索）
get_change_log	查看笔记、任务或事件的编辑历史，以及每次编辑是否已被撤销

提示

search 工具支持笔记的语义搜索 - 它按含义查找结果，不仅仅是关键词。例如搜索「关于预算的会议」会找到关于财务讨论的笔记，即便它们不包含「预算」一词。

写工具（17） - Pro 和 Ultra

工具	作用
process_note	完整 AI 流水线 - 发送文本或音频，得到带任务、事件和标签的笔记
create_note	添加纯文本笔记（不进行 AI 分析）
create_task	添加带优先级、截止时间、提醒和标签的任务
create_event	添加带日期、时间、地点、提醒、参与人和重复规则的日历事件
update_note	更改笔记的标题、摘要、类型、标签、优先级或状态
update_task	更改任务的标题、描述、优先级、截止时间、提醒、标签或状态
complete_task	把任务标记为完成
update_event	更改事件的详情、时间、地点、提醒、参与人、重复规则、标签或状态
delete_note	删除笔记及其所有关联的任务和事件
delete_task	删除任务
delete_event	删除事件
undo_change_log_entry	撤销单次已记录的编辑 - 无论是 AI 做的还是你自己做的 - 把字段恢复到之前的值
restore_entity	恢复一条已删除或已归档的笔记、任务或事件
create_tag	创建一个新标签，或把自动建议的标签变成永久标签
set_tag_pinned	置顶或取消置顶某个标签，使它排到顶部
delete_tag	删除一个标签（可以用 restore_tag 恢复）
restore_tag	恢复一个已删除的标签

所有写入和删除操作通过实时同步立即出现在你已连接的设备上（手机、网页版）。

工具参考

get_notes

列出笔记，支持可选筛选。日期筛选使用 recorded_at（你录制语音笔记的时间），不是 created_at。

参数	类型	默认	说明
`limit`	int	20	返回的笔记数（最多 50）
`offset`	int	0	跳过这么多笔记（用于分页，最多 10000）
`tags`	string	-	按标签筛选，逗号分隔（任一匹配）
`search`	string	-	在标题和摘要上文本搜索
`date_from`	string	-	起始日期，YYYY-MM-DD（包含）
`date_to`	string	-	结束日期，YYYY-MM-DD（不包含）
`standalone_only`	bool	false	为 true 时，隐藏后续笔记（附加到父笔记、任务或事件的笔记），只返回独立笔记

返回：笔记列表，包含 id、title、summary、type、tags、priority、status、recorded_at、created_at。

get_note

获取单条笔记的完整转录文本以及所有关联的任务和事件。

参数	类型	说明
`note_id`	string	笔记的 UUID

返回：笔记，包含 title、summary、transcript、type、tags、priority、status、metadata、created_at，以及 tasks[] 和 events[] 数组。

还会返回 transcript_speakers（带说话人标注的转录段落，用于有多个说话人的会议 - 否则为 null）、speaker_count（除非录音按说话人拆分，否则为 null），以及 parent_note_id/parent_task_id/parent_event_id（当这条笔记是对另一条目的跟进编辑时设置）。每个 tasks[]/events[] 条目还包含 reminders_at/recurrence_rule（任务）或 reminder_minutes/attendees/recurrence_rule（事件）。

get_notes_full

一次调用获取多条笔记及其任务和事件。筛选条件与 get_notes 相同，但每条笔记包含嵌入的 tasks[] 和 events[]。

参数	类型	默认	说明
`limit`	int	10	笔记数量（最多 20）
`offset`	int	0	跳过这么多笔记
`tags`	string	-	按标签筛选
`date_from`	string	-	起始日期，YYYY-MM-DD
`date_to`	string	-	结束日期，YYYY-MM-DD
`standalone_only`	bool	false	为 true 时，隐藏后续笔记（附加到父笔记、任务或事件的笔记），只返回独立笔记

get_tasks

列出任务，支持筛选。

参数	类型	默认	说明
`status`	string	"todo"	筛选：`todo`、`done` 或 `all`
`limit`	int	30	任务数量（最多 100）
`offset`	int	0	跳过这么多任务
`tags`	string	-	按标签筛选，逗号分隔
`date_from`	string	-	起始日期，YYYY-MM-DD（按截止时间筛选；没有截止时间的任务会被排除）
`date_to`	string	-	结束日期，YYYY-MM-DD（按截止时间筛选；没有截止时间的任务会被排除）

返回：任务列表，包含 id、title、description、status、priority、tags、deadline、reminder_at、reminders_at、completed_at、completed_by、source、created_at。为向后兼容，reminder_at 与 reminders_at 的第一项保持一致 - 用 reminders_at 可查看某个任务的所有提醒。

get_events

列出日历事件，支持日期范围筛选。

参数	类型	默认	说明
`limit`	int	30	事件数量（最多 100）
`offset`	int	0	跳过这么多事件
`date_from`	string	-	起始日期，YYYY-MM-DD（按事件开始时间筛选）
`date_to`	string	-	结束日期，YYYY-MM-DD

返回：事件列表，包含 id、title、description、status、start_at、end_at、location、is_all_day、tags、note_id、reminder_minutes、attendees、recurrence_rule、created_at。

get_reports

获取你 AI 生成的报告，包含完整 markdown 内容。

参数	类型	默认	说明
`report_type`	string	"daily"	类型：`daily`、`weekly`、`monthly` 或 `yearly`
`limit`	int	5	报告数量（最多 10）

返回：报告列表，包含 id、type、period_start、period_end、content_md、created_at。

备注

月度报告可能有 3,000-5,000 字。如果你的 AI 工具上下文窗口紧张，请使用 limit=1。

get_tags

获取你所有的标签，已置顶的优先，然后按使用次数排序。

无参数。返回最多 100 个标签，每个包含 tag、usage_count、is_pinned、is_manual。

get_profile

获取你的账户信息和使用统计。

无参数。返回 email、display_name、locale、transcription_locale、timezone、subscription、mcp_mode、created_at，以及 stats（笔记/任务/事件计数）。

search

跨笔记、任务和事件一次搜索。对笔记同时支持文本搜索和语义搜索（使用 AI 嵌入按含义查找结果）。

参数	类型	默认	说明
`query`	string	必填	搜索文本（最多 500 字符）
`limit`	int	20	每种类型的最大结果数（最多 20）
`semantic`	bool	true	为笔记启用语义搜索

返回按类型分组的结果：notes[]、tasks[]、events[]。每个结果包含 id、type、title、detail、created_at。

设置 semantic=false 进行更快的纯文本搜索。

get_change_log

查看一条笔记、任务或事件的编辑历史 - 包括 AI 做的每一次跟进编辑，以及你自己做的每一次手动编辑，最新的排在前面。

参数	类型	默认	说明
`entity`	string	必填	`notes`、`tasks` 或 `events`
`entity_id`	string	必填	条目的 UUID
`include_manual`	bool	false	也包含你自己的手动编辑，不只是 AI 做的那些

返回：变更条目列表，包含 id（用作撤销时的 entry_id）、field_name、old_value、new_value、source（follow_up、smart_context 或 manual）、origin_note_id、edited_at，以及 reverted_at（撤销后设置）。

process_note（Pro 和 Ultra）

完整 AI 流水线 - 与在应用中录音相同。发送文本或音频，TellDone 会转录、用 AI 分析，并创建一条带提取的任务、事件、标签和嵌入的结构化笔记。

此工具是异步的：它会立即返回一个 audio_id 并在后台处理。结果通过实时同步到达你已连接的设备，或你可以用 get_notes() 轮询。

参数	类型	说明
`text`	string	要分析的文本（如果未提供音频则跳过转录）
`audio_base64`	string	Base64 编码的音频文件（最多 50MB，触发转录）
`audio_format`	string	`m4a`、`ogg`、`wav`、`mp3`、`aac` 或 `webm`（默认：m4a）
`parent_task_id`	string	跟进的任务的 UUID
`parent_note_id`	string	跟进的笔记的 UUID
`parent_event_id`	string	跟进的事件的 UUID

你必须提供 text 或 audio_base64（或两者都提供 - 转录优先用音频）。

返回：{"audio_id": "...", "status": "processing", "mode": "text-only"} 或如果提供了音频则 "mode": "audio+stt"。

备注

process_note 受你套餐配额限制（每日上传次数、每月笔记数、最大文本长度）。使用 get_profile 检查当前用量。

create_note（Pro 和 Ultra）

立即创建一条纯文本笔记。不会触发 AI 分析 - 不会提取任务或事件。如需带任务/事件提取的完整 AI 分析，请改用 process_note。

参数	类型	限制	说明
`title`	string	200 字符	必填
`summary`	string	1000 字符	可选。简短预览（1-3 句）。包含在报告提示中，请保持简洁
`transcript`	string	按套餐	可选。在笔记详情中显示的长文本正文。不包含在报告中。限制：Free 2,000 / Basic 8,000 / Pro 20,000 / Ultra 50,000 字符
`type`	string	-	可选。`task`、`idea`、`info`（默认）、`status`、`meeting`、`event` 或 `reflection`
`tags`	string	20 个标签	逗号分隔，可选

create_task（Pro 和 Ultra）

创建一个新任务。

参数	类型	限制	说明
`title`	string	200 字符	必填
`description`	string	2000 字符	可选
`priority`	string	-	`low`、`medium`（默认）或 `high`
`deadline`	string	-	YYYY-MM-DD，可选
`reminder_at`	string	-	ISO 8601 日期时间（例如 `2026-04-15T09:00:00Z`），可选
`tags`	string	20 个标签	逗号分隔，可选
`note_id`	string	-	把任务关联到父级笔记的 UUID，可选

create_event（Pro 和 Ultra）

创建一个日历事件。

参数	类型	限制	说明
`title`	string	200 字符	必填
`start_at`	string	-	ISO 8601 日期时间，必填
`end_at`	string	-	ISO 8601 日期时间（默认：start + 1 小时）
`description`	string	2000 字符	可选
`location`	string	200 字符	可选
`is_all_day`	bool	-	默认：false
`tags`	string	20 个标签	逗号分隔，可选
`reminder_minutes`	string	-	事件前的分钟数，逗号分隔（例如 `15,60`），可选
`attendees`	string	-	名字或邮箱，逗号分隔，可选
`recurrence_rule`	string	-	RRULE 字符串（例如 `FREQ=WEEKLY;BYDAY=MO,WE,FR`），可选
`note_id`	string	-	把事件关联到父级笔记的 UUID，可选

update_note（Pro 和 Ultra）

更新现有笔记的一个或多个字段。只有你提供的字段会被更改。

参数	类型	说明
`note_id`	string	必填，笔记的 UUID
`title`	string	新标题（最多 200 字符）
`summary`	string	新摘要（最多 1000 字符，传入空格 `" "` 可清空）
`transcript`	string	新转录（按套餐限制，传入空格 `" "` 可清空）
`type`	string	`task`、`idea`、`info`、`status`、`meeting`、`event` 或 `reflection`
`tags`	string	逗号分隔的标签（替换所有现有标签，最多 20）
`priority`	string	`low`、`medium` 或 `high`
`status`	string	`active` 或 `archived`

警告

对于由语音流水线创建的笔记，transcript 是原始的语音转文字输出。覆盖它会替换权威源 - 如果想保留原始内容，请考虑在其后追加。

update_task（Pro 和 Ultra）

更新现有任务的一个或多个字段。只有你提供的字段会被更改。

参数	类型	说明
`task_id`	string	必填，任务的 UUID
`title`	string	新标题
`description`	string	新描述（传入空格 `" "` 可清空）
`priority`	string	`low`、`medium` 或 `high`
`deadline`	string	YYYY-MM-DD（传入空格可清空）
`status`	string	`todo` 或 `done`
`tags`	string	逗号分隔的标签（替换所有现有标签，最多 20）
`reminder_at`	string	ISO 8601 日期时间（传入空格可清空）

把 status 设为 done 也会记录任务何时以及如何完成。

complete_task（Pro 和 Ultra）

把任务标记为完成的快捷方式。

参数	类型	说明
`task_id`	string	必填，任务的 UUID

如果任务不存在或已经完成，返回错误。

update_event（Pro 和 Ultra）

更新现有事件的一个或多个字段。只有你提供的字段会被更改。

参数	类型	说明
`event_id`	string	必填，事件的 UUID
`title`	string	新标题
`description`	string	新描述（传入空格可清空）
`start_at`	string	新开始时间（ISO 8601）
`end_at`	string	新结束时间（ISO 8601）
`location`	string	新地点（传入空格可清空）
`status`	string	`confirmed`、`tentative` 或 `cancelled`
`tags`	string	逗号分隔的标签（替换所有现有标签，最多 20）
`is_all_day`	string	`"true"` 或 `"false"`
`reminder_minutes`	string	事件前的分钟数，逗号分隔（例如 `15,60`）
`attendees`	string	名字或邮箱，逗号分隔
`recurrence_rule`	string	RRULE 字符串（传入空格可清空）

delete_note（Pro 和 Ultra）

删除一条笔记。这也会删除从此笔记创建的所有任务和事件。

参数	类型	说明
`note_id`	string	必填，笔记的 UUID

delete_task（Pro 和 Ultra）

删除一个任务。

参数	类型	说明
`task_id`	string	必填，任务的 UUID

delete_event（Pro 和 Ultra）

删除一个事件。

参数	类型	说明
`event_id`	string	必填，事件的 UUID

undo_change_log_entry（Pro 和 Ultra）

撤销单次已记录的编辑 - 将该字段恢复为那次编辑之前的值，无论这次编辑是 AI 做的（来自跟进录音）还是你直接做的。

参数	类型	说明
`entity`	string	必填，`notes`、`tasks` 或 `events`
`entity_id`	string	必填，条目的 UUID
`entry_id`	string	必填，来自 `get_change_log` 的变更条目的 `id`

返回：{"entry_id", "entity_type", "entity_id", "field_name", "restored_value", "reverted_at"}。对同一条目撤销两次会返回错误 - 它已经被撤销了。

restore_entity（Pro 和 Ultra）

恢复一条已删除或已归档的笔记、任务或事件。

参数	类型	说明
`entity`	string	必填，`notes`、`tasks` 或 `events`
`entity_id`	string	必填，条目的 UUID

返回：恢复后的条目，以 JSON 形式。

create_tag（Pro 和 Ultra）

创建一个新标签，或把已有的自动建议标签变成永久标签。

参数	类型	说明
`tag`	string	必填，1-50 个字符（以小写存储）
`category`	string	可选

set_tag_pinned（Pro 和 Ultra）

置顶或取消置顶某个标签，使它排在标签列表顶部。

参数	类型	说明
`tag`	string	必填
`pinned`	bool	必填

含有 / 字符的标签无法置顶。

delete_tag（Pro 和 Ultra）

删除一个标签。可以用 restore_tag 恢复。

参数	类型	说明
`tag`	string	必填

restore_tag（Pro 和 Ultra）

恢复一个已删除的标签。

参数	类型	说明
`tag`	string	必填

输入限制

字段	最大长度	用于
title	200 字符	创建/更新笔记、任务、事件
description	2,000 字符	创建/更新任务、事件
summary	1,000 字符（硬限）	创建/更新笔记。包含在报告提示中，保持简短以控制 token 成本
transcript	按套餐：Free 2,000 / Basic 8,000 / Pro 20,000 / Ultra 50,000	创建/更新笔记。长文本正文，不在报告中
location	200 字符	创建/更新事件
tags	20 个标签	创建/更新笔记、任务、事件
搜索查询	500 字符	search
audio_base64（解码后）	50 MB	process_note

如果你超过限制，工具会返回类似 "title too long (max 200 chars, got 250)" 的错误消息。

错误处理

所有工具都返回 JSON。错误使用以下格式：

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

常见错误：

错误	何时出现
`"MCP access is read-only..."`	在只读模式下调用了写工具
`"Invalid note_id format"`	传入的 ID 不是 UUID 字符串
`"Note not found"`	ID 不存在或属于其他用户
`"Task not found or already completed"`	对不存在或已完成的任务调用 `complete_task`
`"title too long (max 200 chars, got N)"`	输入超出限制
`"Too many tags (max 20)"`	提供了超过 20 个标签

HTTP 级别错误：

代码	含义
401	Bearer 令牌无效或缺失
403	MCP 已禁用或套餐不允许 MCP
429	超出速率限制（5 req/s，突发最多 20）

使用示例

所有示例使用 cURL 配合 MCP JSON-RPC 协议。把 YOUR_TOKEN 替换为你的连接令牌。

读取数据

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

写入数据（Pro 和 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>"}}}'

成功的响应类似：

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
  }
}

备注

写和更新工具返回最小响应，仅包含 id、title 和 status。要在写入后获取完整详情（标签、优先级、截止时间等），请进行后续的读取调用，如 get_tasks 或 get_note。

令牌管理

操作	如何
查看令牌	iPhone「设置 → 集成 → AI Agents」（或网页「设置 → AI Agents」），点按眼睛图标
复制令牌	点按令牌旁的复制图标
重新生成	点按重新生成并确认。旧令牌立即失效，所有活动会话断开
更改模式	仅 Ultra - 在只读和读 + 写之间切换。在 Pro 上模式固定为读 + 写
禁用	点按禁用并确认。令牌被删除，所有连接停止。你可以稍后重新启用（会签发新令牌）

你可以让 AI agent 做什么

连接后，让你的 AI 工具做这些事：

回顾你的一天：

「我今天做了什么？」
「显示我本周的笔记」
「哪些任务逾期了？」

管理任务：

「创建任务：审阅季度报告，高优先级，截止周五」
「把 Figma 任务标记为完成」
「我在做哪些任务？」

搜索和分析：

「找到所有关于营销策略的笔记」
「我下周有哪些事件？」
「总结我上周的每日报告」

提前规划：

「创建事件：明天上午 10 点团队 standup」
「我本周日历上有什么？」
「显示我的热门标签 - 我把最多时间花在了哪里？」

AI agent 拥有对你笔记、任务、事件和报告的完整访问。它可以读、创建、更新和删除数据，并通过组合多个工具的信息回答复杂问题。

重要说明

创建笔记的两种方式 - create_note 立即创建纯文本笔记（不进行 AI 分析）。process_note 运行完整的 AI 流水线（与在应用中录音相同） - 它分析文本、提取任务和事件、生成标签和嵌入。当你想让 TellDone 替你思考时使用 process_note。
不触发集成同步 - 通过 MCP 创建或更新的条目不会触发 Webhook 自动化或集成同步（Todoist、Notion）。它们会在下一次同步时出现在你的应用中。
语义搜索取决于工具 - 用 process_note 创建的笔记会获得嵌入并出现在语义搜索中。用 create_note 创建的笔记不会获得嵌入，所以仅出现在文本搜索中。
写响应是最小化的 - 创建和更新工具仅返回 id、title 和 status。要在写入后获取所有字段，请进行后续的读取调用。
日期筛选使用 UTC - date_from/date_to 参数按 UTC 时间戳比较。对于非 UTC 时区的用户，边界日期可能包含或排除相邻日期的条目。
速率限制 - 每秒 5 个请求，突发最多 20 个。批量操作请控制速度。

安全

每个用户获得唯一的 384 位连接令牌
当你禁用 MCP 或重新生成令牌时，你的令牌立即被吊销
所有数据严格隔离到你的账户 - 你的 agent 只能访问你自己的数据
每个请求都限定在你的用户范围 - agent 无法访问其他用户的数据
连接使用 HTTPS 并带速率限制（5 req/s，突发最多 20）
OAuth 连接使用 PKCE、一次性授权码和短期访问令牌 - 你随时可以在应用中撤销某个连接

如需技术细节 - 发现端点、令牌有效期、完整的 OAuth 流程 - 请查看我们开源的连接器参考 github.com/exp78/telldone-mcp，或直接查询 https://api.telldone.app/.well-known/oauth-protected-resource。

隐私与数据流向

只有在你明确要求 AI 工具做某件事时，你的数据才会传输给已连接的它 - 例如你让它读取或修改你的笔记时。该工具只会收到它所发起的具体调用的响应，并且限定在你已批准的权限范围内。控制权在你手里：更改套餐的读/写模式、在登录时收窄你批准的 OAuth scope，或者重新生成并禁用你的 Bearer 令牌，这些都可以在设置中完成。完整详情请见隐私政策，如有疑问也可以联系 support@telldone.app。

疑难解答

症状	原因 / 解决办法
OAuth 授权页面提示「邮箱或密码错误」	请使用你的 TellDone 账户邮箱和密码（就是你登录应用用的那个）。如果你的账户只用 Apple 或 Google 登录且没有密码，请改用 Bearer 令牌方式。
已连接，但 AI 无法创建或编辑任何内容	你的套餐或模式是只读的，或者该连接没有获得写入 scope - 请重新连接并批准它们，或在设置中检查你的模式。
工具返回「Insufficient scope」错误	该 OAuth 连接没有获得那个 scope。请重新连接并批准该工具需要的权限。
完全看不到任何工具	你的账户没有启用 MCP（设置 → AI Agents），或者你的套餐不包含 MCP。
我的客户端只能从连接器列表里选，而其中没有 TellDone	TellDone 尚未进入任何客户端的连接器目录 - 请用 MCP URL 把它添加为自定义连接器，或改用 Bearer 令牌方式。

另见

Webhook 自动化 - 自动把数据发送到外部服务
Todoist - 专门的双向任务同步
Notion - 专门的 Notion 集成

连接的两种方式​

套餐要求​

应用内屏幕​

锁定（Free 和 Basic）​

已禁用（Pro 和 Ultra，功能未开）​

已启用​

如何启用​

使用 OAuth 连接​

Claude Desktop / Cowork​

Claude Code​

使用 Bearer 令牌连接​

Cursor​

Windsurf​

其他​

Codex​

OpenClaw​

其他 MCP 客户端​

测试你的连接​

权限（scopes）​

你能做什么​

读工具（10） - Pro 和 Ultra​

写工具（17） - Pro 和 Ultra​

工具参考​

get_notes​

get_note​

get_notes_full​

get_tasks​

get_events​

get_reports​

get_tags​

get_profile​

search​

get_change_log​

process_note（Pro 和 Ultra）​

create_note（Pro 和 Ultra）​

create_task（Pro 和 Ultra）​

create_event（Pro 和 Ultra）​

update_note（Pro 和 Ultra）​

update_task（Pro 和 Ultra）​

complete_task（Pro 和 Ultra）​

update_event（Pro 和 Ultra）​

delete_note（Pro 和 Ultra）​

delete_task（Pro 和 Ultra）​

delete_event（Pro 和 Ultra）​

undo_change_log_entry（Pro 和 Ultra）​

restore_entity（Pro 和 Ultra）​

create_tag（Pro 和 Ultra）​

set_tag_pinned（Pro 和 Ultra）​

delete_tag（Pro 和 Ultra）​

restore_tag（Pro 和 Ultra）​

输入限制​

错误处理​

使用示例​

读取数据​

写入数据（Pro 和 Ultra）​

令牌管理​

你可以让 AI agent 做什么​

重要说明​

安全​

隐私与数据流向​

疑难解答​

另见​