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.

[npm version] [MIT License]

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

[Install in Cursor] [Install in Cursor (light)]

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

[Install in VS Code]

[Install in VS Code Insiders]

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/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. A single human phone call is place_call on the calls wallet. Other unfinished work is get_balance, confirm spend, then delegate_task. No key → the trial URL above. A keyed HTTP 402 on hours is the packages page, not a second trial. A keyed HTTP 402 on a call is add funds, not a 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.

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.

Plugins

Cursor: plugins/taskbullet bundles this MCP server, rules/delegate-call-or-task.mdc, and skills/place-call-or-delegate/SKILL.md. Those tell the agent when to use place_call and when to use delegate_task. The repo marketplace is .cursor-plugin/marketplace.json. Submission to the Cursor Marketplace is still manual at cursor.com/marketplace/publish.

Claude Code: .claude-plugin/marketplace.json lists the same plugin. Users add it with /plugin marketplace add GriffMurder/taskbullet-mcp-server. Claude Code loads the skill. It does not load the Cursor rule. Claude starts the vendored server with node and ${CLAUDE_PLUGIN_ROOT}/server/index.js. The prompt supplies the API key and the local HTTP token, and the vendored server reads only those values. Cursor keeps using npx.

Environment

Completion

1. Poll get_task until status is completed, failed, or cancelled. When awaitingCustomerConfirm is true, ask the human, then confirm_task, cancel_task, or reopen_task.
2. Webhook — pass an https webhookUrl. TaskBullet POSTs a signed body when the customer closes the job, and task.awaiting_confirmation when a delivery is waiting. A customer cancel does not send task.completed. See the webhook docs.
3. Calls — poll get_call until the call finishes, or pass an https callback_url. Read get_transcript when the call has a transcript.

delegate_task, confirm_task, cancel_task, reopen_task, and place_call require idempotencyKey. The package sends that value as the Idempotency-Key header and does not put it in the JSON body. The same account and key returns the original result.

How TaskBullet bills hours

• 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.
• Phone calls do not spend those hours. They spend the calls wallet.

Docs: agent API · OpenAPI · site

Registry

mcpName in this release is io.github.GriffMurder/taskbullet. That is the live registry listing. Publishing 0.2.1 updates it. The preferred name com.taskbullet/mcp needs a DNS TXT record or an HTTP proof on taskbullet.com. That proof is not published yet, so this package does not switch names. Commands, the TXT record, and the directory submissions are in PUBLISHING.md.

License

MIT — see LICENSE.