TaskBullet Site Guide MCP server

@taskbullet/mcp-server

MCP server for AI agent → human virtual assistant handoff. When an agent hits a task it cannot finish (phone calls, 2FA, captcha, physical-world actions, subjective QA), it files the brief with a TaskBullet virtual assistant.

There are two servers:

The public site server does not see customer accounts, emails, work history, or internal docs. Task delegation is only on the agent server.

Cloud agents (Cursor cloud, Grok, hosted Claude) should use the hosted agent URL. They cannot run npx.

Tools

delegate_task arguments: title (required), description, priority (low \| normal \| high \| urgent), dueDate, webhookUrl (https), maxHours (default 0.5, max 8), idempotencyKey (optional; a key is generated when omitted). Same tool names and the same required arguments as 0.1.x.

A tblive key files the brief. The customer starts VA hours on Work. awaitingcustomerstart means the job has not started. Do not say the VA has started. Poll get_task until completed, failed, or cancelled, or pass webhookUrl. Customer cancel is cancelled and does not send the completion webhook.

maxHours is a spend cap. Tracked time is what is billed (15-minute rounding). HTTP 402 means a live read is not above zero — buy hours at the addHoursUrl (the packages page, not a new trial). HTTP 422 means the cap does not fit open caps: hours remain, lower maxHours to capRoom or wait. HTTP 503 means hours were unavailable. That is not a buy-hours error.

Never put passwords, OTP codes, recovery keys, cookies, or API keys in a brief. The server drops those locally and the API rejects them.

Quickstart

Create a key at taskbullet.com/dashboard/settings/api-keys. It is shown once. Put it in the client config or the process environment. Do not paste it into chat.

Claude Desktop (stdio)

claudedesktopconfig.json (locations):

{
  "mcpServers": {
    "taskbullet": {
      "command": "npx",
      "args": ["-y", "@taskbullet/mcp-server"],
      "env": {
        "TASKBULLET_API_KEY": "tb_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The four tools show up in the tools panel.

Cursor (hosted streamable HTTP)

~/.cursor/mcp.json or the project .cursor/mcp.json:

{
  "mcpServers": {
    "taskbullet": {
      "url": "https://taskbullet.com/api/agent-mcp",
      "headers": {
        "x-api-key": "tb_live_your_key_here"
      }
    }
  }
}

Laptop stdio, if you would rather run the package locally:

{
  "mcpServers": {
    "taskbullet": {
      "command": "npx",
      "args": ["-y", "@taskbullet/mcp-server"],
      "env": {
        "TASKBULLET_API_KEY": "tb_live_your_key_here"
      }
    }
  }
}

OpenClaw

Shortened. The full README is on GitHub.