@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 tb_live_ key files the brief. The customer starts VA hours on Work. awaiting_customer_start 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)

claude_desktop_config.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

The lobster cannot create the account or mint a key. Tell the human, in order:

1. No account → https://taskbullet.com/get-started?source=openclaw (10 hours, no card)
2. Issue tb_live_… at https://taskbullet.com/dashboard/settings/api-keys (shown once)
3. Paste it into the Gateway env TASKBULLET_API_KEY and point Agent MCP at https://taskbullet.com/api/agent-mcp with header x-api-key. Restart. Never put the key in chat.

Install the skill with openclaw skills install @griffmurder/taskbullet. Then get_balance, confirm spend, and delegate_task. No key → the trial URL above. A keyed HTTP 402 is the packages page, not a second trial.

A local Gateway can also launch this package over stdio (npx -y @taskbullet/mcp-server) with TASKBULLET_API_KEY in the environment.

Public site guide (no key)

Read-only. Safe to add beside the agent server.

{
  "mcpServers": {
    "taskbullet-site": {
      "url": "https://taskbullet.com/api/mcp"
    }
  }
}

Call understand_site, then match_intent. Job seekers are not hire conversions.

Local streamable HTTP

Stdio is the default. --http serves streamable HTTP on loopback:

export TASKBULLET_API_KEY="tb_live_your_key_here"
npx -y @taskbullet/mcp-server --http

Endpoint: http://127.0.0.1:3000/mcp. The key stays in this process. Clients on that machine do not send it.

{
  "mcpServers": {
    "taskbullet": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

The process binds to 127.0.0.1 only. It checks Host and Origin so a browser page cannot use DNS rebinding to spend the key. Listening on any other address requires TASKBULLET_HTTP_TOKEN. Send that token as Authorization: Bearer …. It is not the TaskBullet API key.

There is no server-initiated SSE stream. GET returns 405. Responses are JSON. Requests are limited to 60 per minute per client address, and upstream calls follow the Agent API ceiling of 60 per minute. Bodies over 32 KiB are rejected.

Environment

Example

You: Find a flight from SFO to Austin next Tuesday under $300. If you cannot book it, have someone book it.

Claude: I found Delta at 8:15 AM for $278, but that fare has to be booked by phone. You have hours on the account. I can file this for your assistant — it will not start until you click Start on Work.

[calls delegate_task]

Filed atask_a3f9c2d1 as awaiting_customer_start. Open Work and click Start. I will check get_task after that. I will not invent a confirmation.

Completion

1. Poll get_task until status is completed, failed, or cancelled.
2. Webhook — pass an https webhookUrl. TaskBullet POSTs a signed body when the customer closes the job. A VA checkbox does not send it. A customer cancel does not send it. See the webhook docs.

Pass the same idempotencyKey when retrying a brief. The same account and key returns the original task.

How TaskBullet bills

• Hours are prepaid buckets. They roll over for 90 days.
• Delegated tasks route to the virtual assistant on the account.
• The API call is free. Hours deduct when work is tracked, not when the brief is filed.

Docs: agent API · OpenAPI · site

License

MIT — see LICENSE.