Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@holdon-todo show me my open todos"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Manage HoldOn Todo from Cursor via MCP: list, create, complete, and update todos.
Install holdon-todo from the Cursor Marketplace (or load this repo under ~/.cursor/plugins/local/holdon-todo for local testing).
Open Plugins → Configure and set HoldOn PAT.
Create a token: sign in / register at todo.holdon.ltd → sidebar Extensions & tokens → Create Cursor MCP token (todo:read / todo:write).
Related MCP server: Obsidian Tasks MCP Server
mcp.json){
"mcpServers": {
"holdon-todo": {
"command": "node",
"args": ["/absolute/path/to/holdon-todo-mcp/dist/index.js"],
"env": {
"HOLDON_PAT": "holdon_pat_…"
}
}
}
}Optional: HOLDON_API_BASE (default https://api.holdon.ltd/api/v1).
Tool | Description |
| List groups |
| List todos ( |
| Create a todo |
| Mark done |
| Update content / status |
npm install
npm run prepare-distLocal plugin test: symlink this directory to ~/.cursor/plugins/local/holdon-todo, set HOLDON_PAT in plugin config, reload Cursor.
MIT. See PRIVACY.md.
Mark a HoldOn todo as done (status=2). Call todo_list first if uuid is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | Todo uuid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the resulting state (status=2), but says nothing about reversibility, idempotency, permission requirements, or behavior on an already-completed or invalid uuid for what is a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the action and state transition front-loaded before the conditional uuid hint. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter status-change tool with no output schema, the description covers the action, the resulting status, and how to obtain the uuid. It falls short only on mutation-side details (already-done behavior, failure modes) that an agent would ideally know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single required uuid parameter already documented as 'Todo uuid'. The description adds a workflow hint (fetch via todo_list) but no format, source, or validation detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Mark ... as done') on a specific resource (a HoldOn todo), and the parenthetical 'status=2' pins down the exact state transition. This clearly separates it from siblings like todo_update (generic edit) and todo_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit prerequisite for the ambiguous case: 'Call todo_list first if uuid is unknown.' It does not, however, say when to prefer this over todo_update for closing out a todo, so the alternative-routing is only partially covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a HoldOn todo. Use when the user asks to add a reminder or task. New items are ungrouped; use todo_list to verify.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Todo text, max 500 characters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, and it does add real behavioral context: new items are ungrouped, and todo_list is the verification path. It says nothing about what is returned (e.g., a created id), whether the call is idempotent, or any auth/permission requirement, which leaves meaningful gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler, with the core action front-loaded and the usage condition and default state following immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter create tool with a fully documented schema and no output schema, the description covers action, trigger, default grouping state, and a verification path. The only omission is any statement about the result of a successful create, which is a minor gap at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter (content, max 500 characters) is fully documented in the schema. The description adds no further parameter meaning, so the baseline of 3 applies for a schema that does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Create a HoldOn todo") that an agent can act on directly. It distinguishes the tool from todo_list by naming the verification role of the sibling, but it doesn't contrast with todo_update or todo_complete, so sibling differentiation is only partial.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use when the user asks to add a reminder or task" gives an explicit triggering condition, and "use todo_list to verify" points to a complementary sibling. No exclusions or prerequisites (e.g., grouping requirements, duplicate handling) are given, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List HoldOn todo groups (for matching group uuids when organizing items).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'List' strongly implies a safe read operation, and the purpose note explains why groups are fetched. It adds no detail on return format, pagination, or ordering, but for a zero-param read tool the omission is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the action and resource come first. The parenthetical earns its place by explaining the output's role, though the sentence is very short and could carry slightly more context at no real cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description covers what it returns and why, which is enough for correct invocation. The absence of any note on result shape or count is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the parenthetical does usefully frame what the result (group uuids) is for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (HoldOn todo groups), which clearly separates it from sibling todo_list that lists items rather than groups. The parenthetical clarifies the resource's role, though it doesn't explicitly name a sibling to contrast with since none lists groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical implies the use case — fetching group uuids when organizing items — which gives an agent a reasonable trigger. However, it names no alternatives and states no when-not conditions, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List HoldOn todos. status: 1=open, 2=done; omit for all.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | 1 open / 2 done |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does not meet it. It implies a read-only listing but says nothing about permissions, pagination, ordering, or what a todo record contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and resource, with the parameter semantics appended. Nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter list tool this covers the essentials of purpose and filtering, but with no annotations and no output schema the description never says what the returned list looks like or how large it can get. Adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, and the description earns credit above that by adding the omit-for-all default behavior, which the schema does not state. The 1=open/2=done mapping is repeated from the schema, so no additional credit there.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List HoldOn todos"), which is enough to separate it from todo_create/todo_complete/todo_update and from the differently-scoped todo_groups_list. It never explicitly contrasts itself with a sibling tool, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"omit for all" tells the agent how to get the unfiltered list, which is genuine usage guidance for the one optional param. There is no statement of when this tool should be preferred over the other todo_* siblings, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a HoldOn todo content or status. status: 1=open, 2=done.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | ||
| status | No | ||
| content | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden and mostly doesn't. It is a mutation tool yet says nothing about permissions, whether omitted fields are preserved or cleared, whether the update is reversible, or what happens on an invalid uuid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and resource, with the status mapping following. No filler, though the 'HoldOn' branding adds little for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. Only the status codes are covered; the uuid parameter, update semantics, and error behavior are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and there are no enums, so the description's 'status: 1=open, 2=done' mapping is genuinely additive value the schema lacks. However, uuid and content are entirely unexplained, leaving a third of the parameters undocumented in both places.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Update) and resource (HoldOn todo) plus the two fields it can change (content, status). It does not distinguish itself from the sibling todo_complete, which likely covers the status=2 case, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of how it differs from todo_complete despite an apparent overlap when status=2 (done). The agent is left to guess which tool to call for marking a todo complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0todo_completetodo_createtodo_groups_listtodo_listtodo_updateScored across 5 tools
Most tools target clearly distinct operations (list groups, list todos, create, update). However, todo_complete (mark done via status=2) substantially overlaps with todo_update, which can also set status=2, so an agent could reasonably reach for either when closing a task. Descriptions hint at the distinction but the boundary is not fully sharp.
All names are snake_case and share a consistent 'todo' prefix, which is highly predictable. The one deviation is todo_groups_list, which puts the resource before the verb (noun_noun_verb) while every other tool follows todo_<verb>. Minor but noticeable pattern break.
Five tools is a well-scoped surface for a todo server: listing groups, listing items, and create/update/complete cover the core interaction loop without redundancy or bloat. Each tool earns its place for the stated purpose.
The surface covers create, read, update, and completion of todos plus group listing, which handles most todo workflows. The notable gap is deletion (no todo_delete or group creation), so users cannot remove tasks or create groups; agents can partially work around this by marking items done.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Create, list, and complete todo items through MCP.
