MCP server

TaskCrew ships a Model Context Protocol server so any AI agent — Claude Code, Cursor, Claude Desktop, your own agent — can read and change work in a workspace: create tasks, pick up the next to-do, comment, finish work, read and write wiki pages.

• URL: <PUBLIC_API_URL>/mcp (for local development http://localhost:4000/mcp)
• Transport: Streamable HTTP, stateless (POST /mcp; GET/DELETE answer 405 — there are no sessions)
• Auth: a personal API token: Authorization: Bearer tc_…

Create a token in Settings → Developers & AI agents (/w/<workspace>/settings/developers). The page also shows ready-to-paste setup snippets with your token filled in.

A token acts as you, in one workspace: tools see exactly the projects, lists and wikis you can see, and every change is recorded as yours (activity, notifications and automations fire as if you made it in the app).

Setup#

Claude Code#

claude mcp add --transport http taskcrew http://localhost:4000/mcp --header "Authorization: Bearer tc_…"

Cursor (and other apps with remote MCP + headers)#

~/.cursor/mcp.json:

{
  "mcpServers": {
    "taskcrew": {
      "url": "http://localhost:4000/mcp",
      "headers": { "Authorization": "Bearer tc_…" }
    }
  }
}

Claude Desktop (or apps that only launch local servers)#

Use the mcp-remote bridge (needs Node.js):

{
  "mcpServers": {
    "taskcrew": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4000/mcp", "--header", "Authorization: Bearer tc_…"]
    }
  }
}

Tools#

Lists are referenced by name, key or id, tasks by key (DEV-12) or id, states / labels / custom fields by name, people by email, name or "me", placeholder people (names to plan with, never members) by name in their own arguments. Results are compact JSON; errors come back as tool errors with a message that says how to fix the call (e.g. the valid state names). Tasks in a list's Trash are invisible to every tool (never listed, searched or claimed); there are no tools to delete or restore tasks.

claim_next_task — a task list as a work queue#

Atomically takes the next task of a list and returns its full details:

1. candidates: tasks in a Todo-category state (include_backlog: true adds backlog states), not handled by an AI teammate, and that nobody is assigned to (no person and no placeholder person) or that you are already one of the assignees of (optionally only with label);
2. order: priority (urgent first), then oldest first;
3. you are added as an assignee (anyone already on the task stays) and the task moves to the list's first In progress-category state, with activity entries — in one transaction using SELECT … FOR UPDATE SKIP LOCKED, so agents running in parallel never get the same task.

When nothing is waiting it returns {"task": null, …}.

Placeholder people#

Placeholder people are names to plan with ("Freelance designer"), never members: no email, access or notifications. Tasks list them apart from the people (placeholders: ["Freelance designer"]). create_task takes placeholders; update_task takes add_placeholders / remove_placeholders. A name matches an active placeholder exactly (any case), else the one whose name contains it; an unknown name answers with the active placeholders, an ambiguous one with the matches. An archived one can still be taken off a task. A placeholder's name in assignees is refused with a hint to use these arguments. No tool creates, archives or replaces placeholders (that is done in TaskCrew). AI teammates' create_task and update_task take the same arguments.

Task types#

Every task has a type: the built-in Task (the default), Milestone and Approval, or one of the workspace's own (e.g. Bug), which admins manage in TaskCrew. list_lists shows the types each list allows; create_task and update_task take type by name (any case). A type the list does not allow answers with the ones it does. Approval tasks are answered (approve, request changes, reject) by their assignee in TaskCrew, never by a token or an AI teammate. AI teammates' create_task and update_task take type too.

Estimates#

A task can have an estimate in hours. create_task and update_task take estimate: text like time typed in TaskCrew ("4" or "4h", "1.5", "1h 30m", "90m") or a number of hours, up to 999 h; "" clears it. Tasks read back with estimate: "1 h 30 m" when they have one (list_tasks, get_task and the results of the writes). Something that is not an estimate answers with the format. Workload in hours counts a task as its estimate instead of a typical task. AI teammates' create_task, create_subtask and update_task take estimate too.

Recipe: let Claude Code work through a list#

1. Create a list, e.g. "Agent queue", and add tasks (people, automations and recurring tasks can add more).

2. Connect Claude Code as above.

3. Tell it:

   Use the TaskCrew MCP tools to work through the "Agent queue" list: call claim_next_task; if it returns a task, do the work it describes in this repository; then call complete_task with a short summary (or add_comment and leave it open if you are blocked). Repeat until no task is returned.

Every claimed task shows up as assigned to you and "In progress" in the app in real time; finished tasks move to "Done" with the agent's summary as a comment.

Security notes#

• Only the SHA-256 hash of a token is stored; the token is shown once. Tokens can expire and be revoked any time (Settings → Developers). A token stops working when its owner leaves the workspace.
• Requests with a token are confined to the token's workspace: anything else answers 404.
• Tokens cannot create or revoke tokens, manage workspace members or invites, change project/list membership, or create workspaces — those need a signed-in person.
• Tokens cannot change passwords or call any other account route (/api/auth/* except /api/auth/me).
• There are no time-tracking tools, and AI teammates never log time (a token may log its owner's time through the REST API). A password change or reset does not revoke tokens; review them in Settings → Developers.