Click on "Install 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., "@MCP Todo add 'buy groceries' to my todo list"
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.
A todo list server built with the Model Context Protocol (MCP) that supports both stdio and HTTP transports.
npm install
# For HTTP server (easier testing)
npm run dev:http
# For MCP stdio (client integration)
MCP_STDIO=1 npm run devRelated MCP server: mcp-server-interview
npm install
npm run buildFor use with MCP clients like Cursor:
MCP_STDIO=1 npm run devConfigure in Cursor's .cursor/mcp.json:
{
"mcpServers": {
"todo-mcp": {
"command": "npx",
"args": ["-y", "tsx", "src/server.ts"],
"env": {
"MCP_STDIO": "1"
}
}
}
}For HTTP-based access with session management:
npm run dev MCP_STDIO=1 # Starts MCP stdio server
npm run dev:http # Starts HTTP server on port 3000
# or directly: npx tsx src/http.tsThe server exposes endpoints at http://localhost:3000/mcp:
POST /mcp - JSON-RPC requests
GET /mcp - SSE stream for server notifications
DELETE /mcp - End session
Set TODO_MCP_TOKEN environment variable to enable bearer token authentication:
TODO_MCP_TOKEN=your-secret-token npm run devThen include in requests:
Authorization: Bearer your-secret-tokenAdd todos with unique IDs
List all todos with structured output
Toggle todo completion status
Remove todos by ID
Persistent JSON storage in ~/.mcp-todos.json
Session-based HTTP transport with SSE support
Optional bearer token authentication
list_todos - Get all todos in structured format
add_todo - Add a new todo (requires title)
toggle_todo - Toggle completion status (requires id)
remove_todo - Delete a todo (requires id)
todos://list - JSON resource containing all todos
src/server.ts - Core MCP server with todo logic and stdio transport
src/http.ts - HTTP transport wrapper with Express and session management
Add a todo item
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. 'Add a todo item' implies a write operation, but it doesn't disclose behavioral traits such as permissions needed, whether it's idempotent, error handling, or what happens on success (e.g., returns an ID). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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?
The description is extremely concise with a single sentence, 'Add a todo item', which is front-loaded and wastes no words. It's appropriately sized for a simple tool, though this brevity contributes to gaps in other dimensions.
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?
Given the tool's complexity (a write operation with 1 parameter), lack of annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't cover behavioral aspects, parameter details, or return values, making it inadequate for effective agent use without additional context.
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 input schema has 1 parameter with 0% description coverage, and the description adds no meaning beyond the schema. It doesn't explain what 'title' represents (e.g., the todo's name or content), its format, or constraints. With low schema coverage, the description fails to compensate, leaving the parameter's semantics unclear.
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?
The description 'Add a todo item' clearly states the action (add) and resource (todo item), which is adequate. However, it doesn't differentiate from sibling tools like 'list_todos' or 'remove_todo' beyond the basic verb, making it vague in comparison. It's not tautological but lacks specificity about what 'add' entails versus other operations.
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 description provides no guidance on when to use this tool versus alternatives like 'list_todos' or 'toggle_todo'. It doesn't mention prerequisites, context, or exclusions. While the verb 'add' implies creation, it fails to specify scenarios or constraints, leaving usage unclear relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all todos in a structured format.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| todos | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the basic action. It does not disclose behavioral traits such as whether it returns all todos at once or paginates, if it requires authentication, rate limits, or error handling. This leaves significant gaps for a tool that likely interacts with data.
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?
The description is a single, efficient sentence with zero waste. It is front-loaded, directly stating the purpose without unnecessary details. Every word earns its place, making it easy to parse quickly.
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?
Given the tool's simplicity (0 parameters, output schema exists), the description is minimally adequate. However, with no annotations and siblings implying data operations, it should ideally mention safety (e.g., read-only) or constraints. The output schema helps, but the description lacks context for usage in a todo management system.
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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by specifying 'all todos' and 'structured format', which clarifies scope and output beyond the schema. Baseline is high due to no parameters, but it compensates with useful context.
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?
The description clearly states the action ('Return') and resource ('all todos'), specifying the output format ('structured format'). It distinguishes from siblings like add_todo or remove_todo by focusing on retrieval rather than modification. However, it lacks explicit sibling differentiation, such as noting this is for unfiltered listing versus other query options.
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 guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, context (e.g., after adding todos), or exclusions (e.g., for filtered views). The agent must infer usage from the name and siblings alone, which is insufficient for clear decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a todo by id
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a destructive operation ('Remove'), but doesn't specify if deletion is permanent, reversible, requires specific permissions, or has side effects (e.g., affecting related data). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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?
The description is extremely concise with a single sentence that front-loads the core action. There is zero waste or redundancy, making it efficient for quick understanding, though this brevity contributes to gaps in other dimensions.
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?
Given a destructive tool with no annotations, no output schema, and incomplete parameter documentation, the description is inadequate. It doesn't cover behavioral traits, return values, or error conditions, leaving the agent with insufficient context to use the tool safely and effectively.
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 schema description coverage is 0%, and the description adds no meaning beyond the schema's basic type constraints. It mentions 'id' but doesn't explain what this ID represents (e.g., from 'list_todos'), its format, or valid ranges beyond the schema's 'exclusiveMinimum: 0'. With 1 undocumented parameter, the description fails to compensate for the coverage gap.
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?
The description clearly states the action ('Remove') and resource ('a todo by id'), making the purpose immediately understandable. It distinguishes from siblings like 'add_todo' and 'list_todos' by specifying deletion rather than creation or listing. However, it doesn't explicitly differentiate from 'toggle_todo' which also modifies todos, keeping it from a perfect score.
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 guidance is provided on when to use this tool versus alternatives like 'toggle_todo' (which might mark as done instead of deleting) or prerequisites such as needing an existing todo ID. The description only states what it does, not when it's appropriate, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggle a todo by id
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'toggle' but doesn't disclose behavioral traits such as what 'toggle' does (e.g., changes completion status), whether it's idempotent, or any side effects. This leaves critical 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?
The description is extremely concise—a single sentence with zero waste. It's front-loaded and efficiently states the core action, though this brevity contributes to gaps in other dimensions.
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?
Given the tool's complexity (a mutation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It lacks details on behavior, parameter meaning, and expected outcomes, making it inadequate for reliable agent use.
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 0%, with one parameter 'id' undocumented in the schema. The description adds minimal semantics by specifying 'by id', but doesn't explain the parameter's role (e.g., unique identifier) or constraints beyond what's implied, failing to compensate for the coverage gap.
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?
The description states the action ('toggle') and target ('todo by id'), which is clear but minimal. It doesn't distinguish from siblings like 'add_todo' or 'remove_todo' beyond the verb, leaving ambiguity about what 'toggle' specifically does (e.g., mark complete/incomplete).
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 guidance on when to use this tool versus alternatives like 'remove_todo' or how it relates to 'list_todos'. It implies usage for toggling a todo's state but lacks context on prerequisites (e.g., existing todo ID) or exclusions.
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. Dates show when Glama detected each change.
v1.0.0add_todolist_todosremove_todotoggle_todoEach tool has a clearly distinct purpose with no overlap: add_todo creates items, list_todos retrieves them, remove_todo deletes by ID, and toggle_todo updates completion status. The actions (add, list, remove, toggle) and targets (todos) are unambiguous, making tool selection straightforward for an agent.
All tools follow a consistent verb_noun pattern with snake_case naming: add_todo, list_todos, remove_todo, toggle_todo. The verbs are descriptive and aligned with CRUD operations, and the noun 'todo' is used consistently across all tools, providing a predictable and readable naming convention.
With 4 tools, this server is well-scoped for a todo management domain. Each tool serves a distinct and essential function (create, read, update, delete), and there are no extraneous or missing tools. The count is appropriate for the simple but complete coverage of todo operations.
The tool set provides complete CRUD/lifecycle coverage for todo management: add_todo for creation, list_todos for retrieval, remove_todo for deletion, and toggle_todo for updating completion status. There are no obvious gaps, and agents can perform all core operations without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create, list, and complete todo items through MCP.
Add items to your tidee workspace from ordinary language, read what is there, and mark things done.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
ADHD-friendly tasks, notes & projects for LucidNest - 18 tools, scoped tokens, Streamable HTTP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/CalamityAdam/mcp-todo'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
