MCP integration
Let AI clients like Claude work with your tasks through the Model Context Protocol.
Todebaran can act as a local MCP server. MCP — the Model Context Protocol — is an open standard that lets AI apps connect to tools and data. Point an MCP client like Claude Desktop, Claude Code, Cursor or any other at Todebaran, and it can read and act on your tasks, projects and more — right from the conversation.
This is different from the in-app AI
The in-app AI uses your own model to help you inside Todebaran. MCP is the reverse: it lets a separate AI client, running elsewhere, work with your Todebaran data.
Connect a client#
- Open Settings → AI Settings and find the MCP Server section.
- Press Copy to copy the ready-made configuration.
- Paste it into your AI client's MCP configuration and restart the client.
The configuration is specific to your install and needs no separate Node setup — it runs through Todebaran's own bundled bridge.
Where the configuration goes#
Most clients use the same JSON shape, so the copied snippet works as-is:
| Client | Where |
|---|---|
| Claude Desktop | Settings → Developer → Edit Config, which opens claude_desktop_config.json |
| Claude Code | .mcp.json in a project folder, or run claude mcp add-json |
| Cursor | ~/.cursor/mcp.json |
| Anything else | Wherever that client keeps its MCP server list |
Merge, don't replace
The copied text includes the mcpServers wrapper. If the file already has
other servers in it, add the todebaran entry inside the existing
mcpServers object rather than overwriting the whole file.
The app doesn't need to be open
When your client calls a tool, Todebaran starts in the background automatically — you don't have to launch it first.
What a connected client can do#
Tools — read and act#
A connected client gets a full set of tools. Every name is prefixed
todebaran_, so you can point your client at one directly in a prompt.
| Area | Tools |
|---|---|
| Tasks | list_tasks, get_task, search_tasks, create_task, update_task, complete_task, delete_task |
| Scheduling | schedule_task, unschedule_task, set_deadline |
| Organising | move_to_project, move_to_collection, move_to_inbox, set_task_tags |
| Projects | list_projects, create_project, update_project, delete_project |
| Collections | list_collections, create_collection, update_collection, delete_collection |
| Tags | list_tags, create_tag, update_tag, delete_tag |
| Headings | list_headings, create_heading, update_heading, delete_heading |
| Countdowns | list_countdowns, create_countdown, update_countdown, delete_countdown |
| Journal | list_journal, search_journal, upsert_journal, delete_journal |
| Everything | search — full-text across tasks, projects, collections and slips |
search_tasks is the workhorse for questions: it combines a text query with
filters for completion, project, collection, start date and deadline — including
date ranges and "has no deadline" style filters — and returns results a page at
a time.
Slips aren't exposed as MCP tools — create those in the app or with a deep link. A client can still read them.
Resources — read-only snapshots#
Alongside tools, the server exposes read-only snapshots your client can pull in whole:
| Resource | Contains |
|---|---|
todebaran://tasks | Active tasks |
todebaran://projects | Projects |
todebaran://areas | Areas |
todebaran://shares | Shared spaces |
todebaran://collections | Collections |
todebaran://tags | Tags |
todebaran://headings | Headings |
todebaran://countdowns | Countdowns |
todebaran://slips | Slips |
todebaran://journal | Journal entries |
todebaran://settings | Settings |
How the app behaves in the background#
- Closed app — the first tool call starts Todebaran headless: no window, no Dock icon. It answers, and quits itself after 15 minutes without a request.
- Open it while it's headless — clicking the app in the Dock or Spotlight promotes that same instance to a normal window, and it stops auto-quitting. There's never a second copy of Todebaran running on your data.
- Quit mid-conversation — the next tool call quietly starts it again.
Conventions worth knowing#
These are the rules the tools follow. Your AI client discovers them on its own, but they're handy when you're reading its output or writing precise prompts.
| Thing | Rule |
|---|---|
| Dates | Always YYYY-MM-DD — for example 2026-07-25. There's no time of day. |
| Ids | Projects, collections, tags and headings are referenced by their internal id, which the matching list_ tool returns. |
| Subtasks | Sending subtasks replaces the whole list, so a client updating one has to send them all. |
| Task tags | Same — set_task_tags takes the complete list of tag ids. |
| Search results | Up to 100 per page, 20 by default. |
| Task notes | List and search results leave notes out to stay compact; get_task returns the full text. |
| Journal content | Rich-text HTML, matching what the journal editor writes. |
Deleting things#
Deletions ask the client to confirm explicitly, and they aren't all equal:
- A task goes to the Trash, where you can restore it.
- A project or collection is deleted permanently, along with its tasks.
- Tags, headings, countdowns and journal entries are deleted permanently. Removing a heading keeps the tasks that sat under it.
More capable than deep links#
Deep links can only add things, because any web page can fire one. An MCP client is something you set up and trust, so it gets the full toolset — including editing, completing and deleting. Connect only clients you trust with your data.
Privacy#
The MCP server runs only on your own device — it listens on localhost and is never exposed to the network. Your data stays local, and nothing about this integration passes through Todebaran's servers.
Keep in mind, though, that whatever your AI client reads is sent to that client's model provider as part of its conversation (for example, to Anthropic when you use Claude). Treat it like any other AI use.
Example prompts#
Once connected, you can just ask your AI client:
- "Add a task to call the vet tomorrow."
- "What's overdue in my Work project?"
- "Turn these meeting notes into tasks in Todebaran."
- "Anything in my inbox that's been sitting there? Sort it into projects."
- "Summarise what I wrote in my journal last week."
- "Plan my Friday from what's scheduled and what's due."
If it doesn't work#
Check these first
Restart the AI client after editing its configuration — most clients only read their MCP list at launch. And make sure the JSON is valid: a stray comma is the most common reason a server never appears.
- No Todebaran tools in the client — re-copy the configuration from Settings → AI Settings; it's install-specific, so a snippet copied from another machine or an older install may point at a path that no longer exists.
- Tool calls time out — something else may be holding port
21983, which stops Todebaran from serving requests. Quit whatever is using it, then quit and reopen Todebaran. - It works while Todebaran is open, but not when it's closed — the background launch relies on a properly installed app. Move Todebaran to your Applications folder, then copy the configuration again.
- Still stuck — see Getting help.
Technical details#
For advanced setups: the server speaks Streamable HTTP at
http://127.0.0.1:21983/mcp. The copy-paste configuration uses a bundled stdio
bridge so clients that expect a stdio server can launch it on demand — the paths
differ per platform, but the copied config is always correct for your install.
The same local port also serves a plain HTTP endpoint for scripts that don't
speak MCP: GET /api/actions lists everything available, and
POST /api/action with {"action": "…", "input": {…}} runs one.