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., "@Task Manager MCP Server Create a new task to prepare the monthly report"
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.
An educational full-stack project that extends a Model Context Protocol (MCP) task-manager server with a React front-end that teaches MCP concepts hands-on. The React app acts as an MCP client, exposing Resources, Tools, and Prompts in a single UI with in-app explanations. AG Grid is the primary way tabular data is displayed, making this simultaneously a learning exercise for both MCP and AG Grid.
┌─────────────────────────────────────┐
│ MCP Clients │
│ Claude Desktop Cursor React App │
└────────┬──────────┬────────┬────────┘
│ │ │
STDIO STDIO HTTP/SSE
│ │ │
│ ┌──┴────────┴──┐
│ │ HTTP Proxy │ :3001
│ │ (Node/tsx) │
│ └──────┬───────┘
│ │ STDIO
└──────────────┤
┌──────┴───────┐
│ MCP Server │
│ (Node/TS) │
└──────────────┘MCP Server (src/) — TypeScript/Node, STDIO transport. Exposes Resources, Tools, and Prompts for task management with deadlines.
HTTP/SSE Proxy (proxy/) — Spawns the MCP server as a subprocess and bridges it to the browser over HTTP + Server-Sent Events.
React App (client/) — MCP client UI with AG Grid as the primary data presentation layer, educational copy, and a natural-language chat interface.
Related MCP server: Task API MCP
First, build the MCP server (required once, or after server changes):
npm run buildThen start all three processes in parallel:
npm run devIf you already have stale local processes from an earlier run, use:
npm run dev:cleanThis kills anything currently bound to ports 3001 (proxy) and 5173 (client), then starts everything.
This runs:
Process | URL | Description |
MCP Server | — | Runs via STDIO (spawned by proxy) |
HTTP/SSE Proxy |
| Bridges browser ↔ MCP server |
React Client |
| Educational MCP client UI |
Run each in a separate terminal if you prefer:
# Terminal 1 – MCP server (STDIO, consumed by proxy)
npm run start
# Terminal 2 – HTTP/SSE proxy
npm run dev --prefix proxy
# Terminal 3 – React client
npm run dev --prefix clientThe chat tab requires Ollama running locally. If you skip this, the rest of the app works fine — only the AI chat tab is affected.
Install Ollama:
brew install ollamaOr download from ollama.com/download for other platforms.
Start Ollama (runs in the background on port 11434):
ollama serveOn macOS, Ollama may already be running as a menu bar app after installation. You can verify with:
curl http://localhost:11434/v1/modelsIn a new terminal tab, pull Ollama's default model
ollama pull llama3.1The proxy reads LLM settings from proxy/.env. Copy the example and edit as needed:
cp proxy/.env.example proxy/.envThe defaults point to Ollama (http://localhost:11434, model llama3.1). To use a different model or provider, just edit proxy/.env — any OpenAI-compatible API works (Ollama, OpenAI, Anthropic-compatible, etc.). See proxy/.env.example for examples.
The MCP server works as a standalone app for use with other native MCP clients able to send STDIO, such as Claude desktop.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"task-manager": {
"command": "node",
"args": ["/absolute/path/to/todo-mcp-server/build/index.js"]
}
}
}Replace /absolute/path/to/ with your actual path.
MCP separates concerns: Resources are read-only data by URI; Tools are actions with schema-validated inputs; Prompts are pre-built server-generated messages.
Transport is pluggable: STDIO for native clients, HTTP/SSE for browsers (via proxy).
Schema-driven UIs: Tool input schemas can drive form generation directly in the client.
AG Grid patterns: Column defs, multiple data sources, client-side sort/filter — practised across every panel.
LLM + MCP: An LLM can interpret natural language and select MCP operations, acting as a reasoning layer on top of a structured protocol.
Create a new task
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Task title | |
| description | Yes | Task description | |
| priority | No | Task priority |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Create a new task' implies a write/mutation operation but reveals nothing about permissions needed, side effects, error conditions, rate limits, or what happens on success/failure. This is inadequate for a mutation tool with zero annotation coverage.
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 three-word phrase—with zero wasted words. It's front-loaded and efficiently communicates the core action, though this brevity comes at the cost of completeness.
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 mutation tool with no annotations and no output schema, the description is completely inadequate. It doesn't explain what the tool returns, error handling, system context, or behavioral traits. The 100% schema coverage helps with parameters but doesn't compensate for the lack of operational context needed for effective tool 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?
The description adds no parameter information beyond what's in the schema. However, schema description coverage is 100%, with clear documentation for all three parameters (title, description, priority including enum values). This meets the baseline of 3 where the schema does the heavy lifting, though the description contributes nothing extra.
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 'Create a new task' is a tautology that merely restates the tool name. It specifies the verb ('create') and resource ('task') but lacks any distinguishing details about what kind of task or system context. Compared to siblings like 'delete_task' and 'update_task_status', it doesn't differentiate scope or functionality beyond the basic action.
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. It doesn't mention prerequisites, when-not-to-use scenarios, or how it relates to sibling tools like 'get_task' or 'update_task_status'. There's no implied context or explicit usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a task
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates destruction but omits critical details like whether deletion is hard or soft, required permissions, or side effects on related 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?
At one sentence, it is extremely concise but under-specified. Conciseness should not sacrifice completeness; this misses critical information.
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 simple tool with one parameter and no output schema, the description still lacks completeness. It does not mention return values, constraints, or consequences of deletion.
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 the 'id' parameter described as 'Task ID'. The description adds nothing beyond the schema, but given full coverage, the baseline of 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?
The description 'Delete a task' is a tautology that merely restates the tool name without specifying the scope or type of task. It does not distinguish this from actions like marking a task as complete.
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 such as update_task or other deletion tools. The context signals list related siblings but the description offers no direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific task
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Task ID |
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 states the tool 'Get details' which implies a read-only operation, but doesn't specify if it's safe, requires authentication, has rate limits, or what happens with invalid IDs. It lacks critical behavioral traits beyond the basic action.
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 that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple tool, though it could be more front-loaded with key details if expanded.
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 (1 parameter, no output schema, no annotations), the description is incomplete. It doesn't cover return values, error handling, or behavioral context, leaving gaps that could hinder an AI agent's correct invocation despite the straightforward schema.
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 100% description coverage, with the 'id' parameter documented as 'Task ID'. The description adds no additional meaning beyond this, as it doesn't explain parameter usage, format, or constraints. Baseline 3 is appropriate since the schema handles the heavy lifting.
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 'Get details of a specific task' clearly states the verb ('Get') and resource ('task'), but it's vague about what 'details' include and doesn't differentiate from siblings like 'update_task_status' which might also retrieve task information. It avoids tautology by not just restating the name, but lacks specificity.
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 doesn't mention prerequisites (e.g., needing a valid task ID), exclusions, or comparisons to siblings like 'create_task' or 'delete_task'. The description implies usage for retrieving details but offers no contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the status of a task
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Task ID | |
| status | Yes | New status |
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 states 'update' implies a mutation, but doesn't disclose permissions needed, whether changes are reversible, rate limits, or what happens on success/failure. This is a significant gap for a mutation tool with zero annotation coverage.
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—'Update the status of a task' is front-loaded and directly conveys the core action without unnecessary details. Every word earns its place, making it highly concise.
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 and no output schema), the description is incomplete. It doesn't explain behavioral traits, error handling, or return values, leaving gaps that could hinder an AI agent's ability to invoke it correctly despite the clear schema.
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%, with both parameters ('id' and 'status') documented in the schema, including an enum for 'status'. The description adds no additional meaning beyond what the schema provides (e.g., no context on ID format or status transitions), so it meets the baseline for high schema coverage.
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 'Update the status of a task' clearly states the verb ('update') and resource ('task status'), making the purpose understandable. However, it lacks specificity about what 'status' entails or how it differs from other task operations, and it doesn't distinguish from siblings like 'create_task' or 'delete_task' beyond the basic action.
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. The description doesn't mention prerequisites (e.g., needing an existing task ID), exclusions, or comparisons to siblings like 'get_task' for reading status or 'delete_task' for removal. Usage is implied from the name but not explicitly stated.
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.
v1.0.0create_taskdelete_taskget_taskupdate_task_statusScored across 4 tools
Each tool has a clearly distinct purpose with no overlap: create, delete, get, and update_status target different operations on tasks. An agent can easily distinguish between them without confusion.
All tool names follow a consistent verb_noun pattern (e.g., create_task, delete_task), with the slight variation in update_task_status still adhering to the same style. There are no mixed conventions or deviations.
With only 4 tools, the set feels thin for a task management domain, lacking operations like listing tasks or handling priorities. While core CRUD is covered, the count is borderline minimal for typical agent workflows.
The tools cover basic CRUD operations (create, get, delete, update_status), but there are notable gaps such as no list_tasks tool for retrieval of multiple tasks, which could hinder agent efficiency in browsing or filtering tasks.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Model Context Protocol server for todo.vu task management and time tracking.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.