MCP 2025-06-18

task_list

List project tasks, across every project or one, in board order. Filter by status and assignee: assignee me lists your own tasks, unassigned lists tasks nobody has claimed. Use status ready with assignee unassigned to find work to pick up. When partial is true, more may match: call again with the same filters and the returned cursor until partial is false.

Scopes

The agent key needs these scopes. The server also checks access to each record before returning data or changing it.

read:projects

Input schema

This schema is shared with tools/list, including the required fields and additionalProperties rules.

Synthetic example · JSON

{
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "Project name, key (DEV) or ID. Omit for every project."
    },
    "status": {
      "type": "string",
      "description": "Status name (Ready, In progress), kind (backlog, ready, active, waiting, review, done) or ID"
    },
    "assignee": {
      "type": "string",
      "description": "me, unassigned, anyone, or an actor ID"
    },
    "text": {
      "type": "string",
      "description": "Words to search for"
    },
    "sourceUrl": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Only the tasks filed for this https source link, such as a Slack message URL; the other filters still apply"
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "description": "The cursor from the previous task_list call with the same filters"
    }
  },
  "required": [],
  "additionalProperties": false
}

Call this tool

Send it as POST https://www.specifywork.com/api/mcp. Authorization: Bearer <agent key>, a key that starts with sw_agent. Replace the example values with records your key can reach.

Synthetic example · JSON

{
  "jsonrpc": "2.0",
  "id": "example_task_list",
  "method": "tools/call",
  "params": {
    "name": "task_list",
    "arguments": {}
  }
}

Read the result before continuing

Tasks in board order, whether more may match, and the next cursor.

A call returns content[0].text with the JSON result and structuredContent.result with the same value. A refused call returns isError: true and the error code in content[0].text.

A request being accepted is not proof of an external action completing. Keep correlation IDs and mutation idempotency keys unchanged across safe retries.