AI Agents (MCP)
MCP works on all plans. Free and Basic get read-only access to all 10 read tools (Free is limited to 100 requests a day). Pro and Ultra get full Read & Write access (27 tools) and can switch to read-only mode if they prefer.
MCP (Model Context Protocol) lets you connect AI assistants such as ChatGPT and Claude, coding assistants, and automation tools directly to your TellDone data. Once connected, your assistant can read your notes, tasks, events, reports, tags, and change history. On Pro and up, it can also create, update, delete, and restore items. There are 27 tools: 10 for reading (every plan) and 17 for writing (Pro and up).
On the iPhone, Settings > Integrations > AI Agents (MCP) opens the MCP setup screen with your access token masked by default:

And on the web:

Two ways to connect
There are two ways to connect an AI client:
- Sign in with TellDone (OAuth) (recommended) - you sign in with your TellDone account and approve what the app asks for. ChatGPT and Claude use this, and there's no token to copy.
- Bearer token - copy your access token from Settings and paste it into your client's config. Simplest for scripts, command-line tools, and clients that don't have a built-in OAuth flow.
| Client | Recommended |
|---|---|
| ChatGPT (chatgpt.com or the ChatGPT desktop app, not the mobile app) | OAuth - add a custom MCP server with the MCP URL, then sign in |
| Claude (website, Desktop, iPhone app) / Cowork | OAuth - add a custom connector with the MCP URL, then sign in |
| Claude Code (CLI) | Bearer token for now - add the Authorization header with your token |
| Scripts or your own code | Bearer token - simplest to automate |
| A client that only supports picking from a directory of listed connectors | Add TellDone as a custom connector with the MCP URL, or use a bearer token. TellDone isn't in any connector directory yet |
Plan requirements
| Plan | MCP |
|---|---|
| Free | Read-only (10 read tools), 100 requests a day |
| Basic | Read-only (10 read tools), no daily limit |
| Pro | Read & Write (27 tools) - can switch to Read-only mode |
| Ultra | Read & Write (27 tools) - can switch to Read-only mode |
The 100-requests-a-day limit on Free counts tool calls only. Connecting, signing in, and listing tools don't count. The day follows the time zone saved in your account and resets at midnight. When you reach the limit, your assistant gets a message saying so. Write tools are refused on Free and Basic. With an access token, they reply that the connection is read-only and that creating and editing needs Pro and up. With sign-in (OAuth), most of them reply "Insufficient scope", because Free and Basic connections never get write permissions.
The in-app screen
Open Settings > Integrations, and in the AI Agents section tap AI Agents (MCP). The screen says "Let ChatGPT, Claude, and other AI assistants work with your TellDone notes, tasks, and events." and shows your plan:
- Free: "Your plan: Read-only access, 100 requests a day. Writing comes with Pro."
- Basic: "Your plan: Read-only access"
- Pro and Ultra: "Your plan: Read & Write access"
While MCP is off, tap Enable to turn it on.
Once enabled, the screen shows:
- Access mode (Pro and Ultra) - choose Read-only or Read & Write at any time.
- Connect an assistant - steps for ChatGPT, Claude, and Another assistant. You sign in to TellDone inside the assistant, so no token is needed.
- Connected apps - the assistants you have connected, each with a Disconnect button. It stays empty until the first connection.
- For developers (collapsed by default) - the Access Token field (hidden, with Show / Hide and Copy), Regenerate Token, and a Claude Code / Cursor / Other switch with ready-made text and its own Copy button. Claude Code gives you the
claude mcp addcommand, Cursor gives you the JSON for.cursor/mcp.json, and Other lists the server address, the OAuth sign-in option, and theAuthorization: Bearerheader. While the token is hidden, the snippets showYOUR_TOKEN. Tap Show and they contain your real token.
The web has the same controls in a different layout, with no collapsed developer section: the OAuth address with a Copy button, your token controls, Connected apps with Disconnect, and Manual bearer token setup with six client choices (Claude Code, Cursor, Windsurf, Codex, OpenClaw and cURL). On the web, the snippets always contain your real token, even while the token field is hidden, so treat them like the token itself.
- Documentation - a link to this page.
- Disable - turns MCP off. You confirm with "This will revoke access for all connected AI tools." Your token is deleted and all connections stop. If you enable MCP again, you get a new token, and apps connected with sign-in (OAuth) work again without signing in. To remove an app for good, tap Disconnect under Connected apps.
Keep your access token private. Anyone with the token can access your TellDone data. Tap Regenerate Token if you ever suspect it has leaked.
How to enable
You can configure MCP from either platform:
- iPhone: Settings > Integrations > AI Agents (MCP)
- Web: app.telldone.app > Settings > Integrations > AI agents (MCP)
Steps:
- Tap Enable.
- On Pro and Ultra, choose your access mode (Read-only or Read & Write). Free and Basic are read-only.
- To connect ChatGPT or Claude, tap it under Connect an assistant and follow the steps (see below). No token is needed.
- For a coding client on iPhone, open For developers, tap Show, pick Claude Code, Cursor, or Other, and tap Copy under the snippet. If you copy before tapping Show, the snippet has
YOUR_TOKENin place of your token. On the web, pick your client under Manual bearer token setup and copy the snippet; it already contains your token. - Paste the snippet into your client or its config file.
Connecting with OAuth
OAuth is the recommended path for ChatGPT, Claude, and Cowork - you sign in with your TellDone account instead of copying a token.
MCP URL for OAuth: https://api.telldone.app/mcp/user
The same server also answers at https://api.telldone.app/mcp/user/mcp, and both addresses accept a bearer token. For OAuth sign-in, use the first one.
ChatGPT
You can add a custom MCP server on chatgpt.com or in the ChatGPT desktop app. The ChatGPT mobile app can't add custom connectors, and the TellDone app puts it this way: "The ChatGPT app only adds connectors from its catalog." Tap Send the steps to my computer in TellDone to get the instructions on a computer. Once added there, TellDone is available in the ChatGPT mobile app too.
The steps in the app:
- On a computer, open chatgpt.com/plugins, click Add and choose Add custom MCP server.
- Name it TellDone, paste the address below (
https://api.telldone.app/mcp/user) and choose OAuth. - Confirm and install it, then sign in to TellDone and allow access.
See OpenAI's guide on custom MCP servers if the menu names change.
Claude (website, Desktop, iPhone app) / Cowork
The steps in the app:
- In Claude, open Customize → Connectors and tap Add custom connector.
- Paste the address below (
https://api.telldone.app/mcp/user). - Sign in to TellDone and allow access.
When you sign in, TellDone's consent page shows which app is asking for access and the exact permissions it wants. Sign in with your TellDone email and password and click Allow access, or tap Sign in with Apple or Sign in with Google, which approves the access in the same step. Claude connects on its own - there's no token to copy.
If the menu names change, see Anthropic's guide on adding a custom connector.
Connecting with a bearer token
For Claude Code, Cursor, and other clients without built-in OAuth sign-in, paste your access token directly into the client's config. Replace YOUR_TOKEN with the token from your settings in all examples below.
Claude Code (bearer token)
claude mcp add --transport http telldone \
https://api.telldone.app/mcp/user/mcp \
--header "Authorization: Bearer YOUR_TOKEN"
You don't have to type this yourself: in Settings > Integrations > AI Agents (MCP) > For developers, tap Show, choose Claude Code, and tap Copy. The copied command already contains your token.
Cursor
Add to .cursor/mcp.json (or copy it from For developers > Cursor after tapping Show):
{
"mcpServers": {
"telldone": {
"url": "https://api.telldone.app/mcp/user/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
Other clients
Settings for other MCP clients:
Codex
Add to 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
Other MCP clients
Any tool that supports MCP over HTTP can connect. Use the endpoint https://api.telldone.app/mcp/user/mcp with a Bearer YOUR_TOKEN authorization header.
If your client or proxy reserves the Authorization header (for example, some Smithery-style gateways), send the token in X-MCP-Token: YOUR_TOKEN instead. Both headers work; if both are present, Authorization wins.
Testing your connection
You can verify your token works with a simple cURL command:
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}'
A successful response lists all available tools.
Permissions (scopes)
OAuth connections are scoped - during sign-in you see exactly what the client is asking for and approve it explicitly.
| Scope | Lets the app... |
|---|---|
notes:read | Read your notes and open full note details (the search tool also needs tasks:read and events:read) |
notes:write | Create, edit and delete notes (process_note also needs tasks:write and events:write) |
tasks:read / tasks:write | Read / create, edit, complete, and delete tasks |
events:read / events:write | Read / create, edit, and delete events |
reports:read | Read your daily, weekly, monthly, and yearly reports |
tags:read / tags:write | List your tags / create, pin, delete, and restore tags |
profile:read | Read your account info and subscription |
offline_access | Stay signed in (issues a refresh token so you don't have to sign in again each session) |
Scopes limit what a connection can do: a connection with only notes:read can't call a write tool. Your plan sets a second limit on top.
Bearer-token connections aren't scoped individually - they're governed by your plan's read/write mode only.
What you can do
Read tools (10) - all plans
| Tool | What it does |
|---|---|
| get_notes | List notes with filters (tags, date range, text search) |
| get_note | View a single note with its child tasks, events, and full transcript |
| get_notes_full | Get multiple notes with embedded tasks and events in one call |
| get_tasks | List tasks filtered by status (to-do, done, all), tags, or dates |
| get_events | List calendar events, filter by date range |
| get_reports | Read your daily, weekly, monthly, and yearly reports (full markdown) |
| get_tags | View all your tags sorted by usage |
| get_profile | See your account info and how many notes, tasks and events you have |
| search | Search across notes, tasks, and events (text + semantic search for notes) |
| get_change_log | See the edit history of a note, task, or event, and whether each edit has been undone |
The search tool supports semantic search for notes - it finds results by meaning, not just keywords. For example, searching "meetings about budget" will find notes about financial discussions even if they don't contain the word "budget."