TaskBullet Site Guide

Your AI agent can place a real phone call.

A person dials the number. Your agent gets the answers back. The server is @taskbullet/mcp-server.

Pricing

$2.50 for the first minute, then $1 per additional minute. The charge comes from the calls wallet, not from prepaid VA hours. US and Canada numbers only. Recording is not available. A system failure that never dials is fully refunded.

get_balance shows balance_cents (spendable after open holds), holds_cents, and wallet_cents. The default max_minutes is 5. At the rate above, five minutes is $6.50. validate_call returns hold_cents for the body you are about to send, and it places no hold. Use hold_cents.

HTTP 402 payment_required means the wallet cannot cover the hold. Add funds at addFundsUrl. That read does not create a Stripe session. Calls are pay-as-you-go. There is no trial.

Example prompts

Copy one of these into the agent after the server is installed. Put the real US or Canada number in the prompt. Do not put a password, a one-time code, or the API key in it.

Book an appointment:

Call the dentist and book me the earliest appointment next Tuesday after 1pm. The office is Bright Smile Dental at (801) 555-0148. Ask which times they have, book one, and bring back the time and any confirmation number. Confirm the hold with me before you place the call. Do not record it.

Call a vendor to check an order:

Call Northwind Supply at (415) 555-0199 and check order NW-10442. Ask whether it shipped, the carrier, and the tracking number. Confirm the hold with me before you place the call. US number, no recording.

Confirm a reservation:

Call Harbor Grill at (206) 555-0177 and confirm the reservation for Alex Chen, party of 4, this Friday at 7:00pm. Ask them to say the name, time, and party size back. Confirm the hold with me before you place the call. Do not record it.

Install

Create a key at taskbullet.com/dashboard/settings/api-keys. It is shown once. The buttons below install a placeholder tb_live_your_key_here. Replace that placeholder in the client config before the first call. Do not paste the real key into chat.

The config runs npx -y @taskbullet/mcp-server on your machine. Cloud agents that cannot run npx should use the hosted URL in Cursor and cloud agents.

Cursor

GitHub does not open cursor:// links. Copy this into a browser:

cursor://anysphere.cursor-deeplink/mcp/install?name=taskbullet&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0YXNrYnVsbGV0L21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlRBU0tCVUxMRVRfQVBJX0tFWSI6InRiX2xpdmVfeW91cl9rZXlfaGVyZSJ9fQ==

Decoded config:

{

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

VS Code

vscode:mcp/install? and vscode-insiders:mcp/install? carry the same URL-encoded JSON. The name is inside that JSON:

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

Claude Code

claude mcp add taskbullet --env TASKBULLET_API_KEY=tb_live_your_key_here -- npx -y @taskbullet/mcp-server

Replace tb_live_your_key_here before you run it. From a marketplace, after this repo is on the default branch:

/plugin marketplace add GriffMurder/taskbullet-mcp-server

Then install taskbullet@taskbullet. The plugin prompts for the key. It does not read a key out of the shell.

JSON

Claude Desktop and any other stdio client:

{

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

claude_desktop_config.json locations are in the MCP quickstart. Restart the app after you save the file.

Tools

Names, arguments, and limits below match the code in src/server.ts.

delegate_task arguments: title (required, max 5000), description (max 8000), priority (low \| normal \| high \| urgent, default normal), dueDate, sourceAgent, webhookUrl (https), maxHours (default 0.5, max 8), idempotencyKey (required). The same value is sent as the Idempotency-Key header and is not put in the JSON body. A repeat returns the original task.

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 assistant has started. Poll get_task until completed, failed, or cancelled, or pass webhookUrl. When get_task shows awaitingCustomerConfirm, ask the human, then confirm_task, cancel_task, or reopen_task. Do not confirm, cancel, or reopen without the human. Customer cancel is cancelled and does not send the completion webhook. If nobody confirms, an agent-created task confirms itself after 3 days.

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 or a call. The server drops those locally and the API rejects them.

Human phone calls use place_call, not delegate_task. Required fields are phone, business_name, purpose (info, scheduling, account_servicing, or vendor_ops), goal (max 4000), questions (1 to 20 items of {id, ask, type?}, id max 80, ask max 1000), on_behalf_of, deadline (ISO-8601), consent_attestation (true), and idempotencyKey. max_attempts defaults to 3 and maxes at 5. max_minutes defaults to 5 and maxes at 60. language is en, fil, tl, war, or ceb.

Only US and Canada numbers can be placed. record_call must be false or omitted. True is rejected locally and nothing is sent. The hold is the full call: the first minute is the tier minimum, then the per-minute rate. A tier 1 call at the default 5 minutes holds $6.50. validate_call is the same body without idempotencyKey, and its hold_cents is the figure to trust. valid stays true when the wallet is short. warnings then include insufficient_balance. place_call is pay-as-you-go from the calls wallet. Poll get_call, or pass an https callback_url. A call outside weekday 09:00–17:00 in the recipient's time zone needs allow_outside_business_hours: true after the customer confirms. The deadline then needs 60 minutes of clock time.

update_call takes call_id plus any of the same body fields. get_call, cancel_call, and get_transcript take call_id.

TaskBullet Hub

TaskBullet Hub is one MCP connection for agents, with human backup.

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.

Cursor and cloud agents

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

{

"mcpServers": { "taskbullet": { "url": "https://taskbullet.com/api/agent-mcp", "headers": { "x-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/dashboa