The complete guide to integrating Syncflow with Claude Code via the Model Context Protocol. Manage tasks, decompose work, and track progress without leaving your terminal.
Why Syncflow + AI assistants
Without Syncflow
With Syncflow
What is MCP?
The Model Context Protocol (MCP)is an open standard that lets AI assistants like Claude Code call external tools directly. Instead of pasting curl commands into chat, Claude can call Syncflow tools natively — listing tasks, creating new ones, decomposing them, and updating crumbs all within a natural conversation.
Architecture
The Syncflow MCP server runs locally on your machine using stdio transport:
Claude Code ↔ MCP Server (local, stdio) ↔ Syncflow API (cloud)
your terminal Node.js process syncflow.mePrerequisites
Generate an API key
Build the MCP server
cd mcp-server && npm install && npm run buildRegister with Claude Code
claude mcp add --transport stdio \
-e SYNCFLOW_API_KEY=your_key \
syncflow -- node /path/to/mcp-server/dist/server.jsReplace /path/to/mcp-server with the actual path where you cloned or installed the MCP server, and your_key with your Syncflow API key.
Verify it works
list_tasks tool and show your tasks.list_tasks— List all tasks with progressReturns all your Syncflow tasks with their crumbs and completion status. No parameters needed.
| Parameter | Type | Required |
|---|---|---|
| No parameters | ||
You: "What tasks do I have?"
Claude: [list_tasks] → Found 3 task(s):
- Build auth system (ID: abc123) — 4/8 crumbs done (~120 min)
- Design landing page (ID: def456) — not decomposed
- Write API tests (ID: ghi789) — completedcreate_task— Create a new taskCreates a new task in Syncflow. Provide a clear title and detailed description for best AI decomposition results.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | required | Short task title |
description | string | required | Detailed description — more context means better decomposition |
priority | number | optional | 1 = low, 2 = medium, 3 = high |
deadline | string | optional | ISO 8601 deadline date |
aiInstructions | string | optional | Hints for the AI decomposer, e.g. "break into 15-min chunks" |
You: "I need to build a REST API for user management"
Claude: [create_task] → Task created: Build REST API (ID: abc123)
Next step: use decompose_task to break it into crumbs.get_task— Get full task detailsReturns a task with all crumbs, descriptions, time estimates, and statuses.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | required | The task ID |
You: "Show me the full breakdown of abc123"
Claude: [get_task] →
## Build REST API
7 crumbs (~150 min total)
[x] Set up Express with TypeScript (20 min)
[ ] Design user schema with Prisma (15 min)
[ ] Implement registration endpoint (25 min)
...decompose_task— AI decompositionUses AI to break a task into small, actionable crumbs with time estimates. The task must not already be decomposed. Respects plan limits (free: 5/month).
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | required | The task ID to decompose |
You: "Break it down"
Claude: [decompose_task] → Task decomposed into 7 crumbs (~150 min total):
1. Set up Express with TypeScript (20 min)
2. Design user schema with Prisma (15 min)
3. Implement registration endpoint (25 min)
4. Add JWT authentication (30 min)
5. Build login/logout routes (20 min)
6. Add input validation with Zod (15 min)
7. Write integration tests (25 min)next_crumb— What's next?Returns the next pending crumb for a task, including description and time estimate.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | required | The task ID |
You: "What's next?"
Claude: [next_crumb] →
Next crumb for "Build REST API":
Design user schema with Prisma (15 min)
ID: crumb_456
5 more crumb(s) remaining after this one.update_crumb— Mark done / update crumbUpdates a crumb's status, title, description, or time estimate.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | required | The task ID |
crumbId | string | required | The crumb ID |
status | enum | optional | "pending" | "in_progress" | "done" | "skipped" |
title | string | optional | New title |
description | string | optional | New description |
estimatedMinutes | number | optional | New time estimate in minutes |
You: "Done with that one"
Claude: [update_crumb] → Crumb updated: Design user schema → doneget_usage— Check plan & limitsReturns your current plan, decomposition usage, task count, and reset date.
| Parameter | Type | Required |
|---|---|---|
| No parameters | ||
You: "How many decompositions do I have left?"
Claude: [get_usage] →
Plan: free
Decompositions this month: 3/5
Tasks created: 12
Can decompose: Yes
Resets: 4/1/2026delete_task— Delete a taskPermanently deletes a task and all its crumbs. This cannot be undone.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | string | required | The task ID to delete |
You: "Delete that old task"
Claude: [delete_task] → Task deleted successfully.Quick: Create + Decompose + Start
You:"Create a task called 'Build checkout page' with high priority and decompose it into small steps."
Claude: Creates the task using create_task, then calls decompose_task to generate crumbs. Shows you the plan and asks if you want to adjust anything.
You:"What's my next crumb?"
Claude: Calls next_crumb and tells you what to work on, including the description and time estimate.
You:"Done with that one."
Claude: Calls update_crumb to mark it complete and shows you the next one.
Full day: 9 AM to 6 PM with Claude Code + Syncflow
Plan the day
Open Syncflow on your phone. See your dashboard: 3 tasks in progress, 2-day streak. Tap into "Build auth system" — 4 crumbs left.
Start coding
Open terminal. Claude already knows your tasks via MCP. Ask: "What's my next crumb?" → "Set up Authentication with GitHub provider (20 min)". Say: "Do it." Claude writes the code.
Mark done, move on
"Mark it done." Claude calls update_crumb→ your streak updates, progress bar moves. "What's next?" → "Add session middleware (15 min)". You keep flowing.
New idea at lunch
You think of a new project on your phone. Create a task in Syncflow: "Build a CLI tool for data migration". Tap Decompose — AI creates 6 crumbs. You refine them, reorder two, delete one that's redundant.
Afternoon deep work
Back at your desk. "List my tasks" — Claude shows both projects with progress. You pick the new one. Each crumb is a perfect-sized prompt for Claude Code. Focused, scoped, no overwhelm.
Review progress
8 crumbs completed today. 3-day streak. You can see exactly what you did and what's left. Tomorrow you'll pick up from crumb 5 without re-explaining anything.
Progress tracking: Check usage, streaks, mark done
You:"How many decompositions do I have left this month?"
Claude: Calls get_usage→ "Plan: free. Decompositions: 3/5 this month. Resets April 1."
You:"Show me everything on my auth task"
Claude: Calls get_task→ shows all 8 crumbs with statuses, estimates, and descriptions. 4 done, 4 pending.
You:"Skip crumb 5, it's not needed anymore"
Claude: Calls update_crumbwith status "skipped" → "Crumb updated: Add rate limiting → skipped"
Environment variables
| Variable | Required | Description |
|---|---|---|
SYNCFLOW_API_KEY | required | Your Syncflow API key (starts with sf_). Generate at Settings → API Keys |
SYNCFLOW_API_URL | optional | API base URL. Defaults to https://syncflow.me. Override for self-hosted or development instances. |
Troubleshooting
"Error: SYNCFLOW_API_KEY environment variable is required"
The MCP server cannot find your API key. Make sure you passed -e SYNCFLOW_API_KEY=your_key when registering the server with claude mcp add.
Claude does not recognize Syncflow tools
Verify the server is registered: run claude mcp listand check that "syncflow" appears. If not, re-run the claude mcp add command from the setup steps above.
"Failed to list tasks (401)"
Your API key is invalid or expired. Generate a new one in Settings → API Keys and update the MCP server registration.
"Cannot find module dist/server.js"
The server has not been built. Run cd mcp-server && npm run build first, then verify dist/server.js exists.
Decomposition fails with "limit reached"
You have used all your monthly decompositions. Use get_usage to check your limits. Upgrade your plan or wait for the monthly reset.