TaskBullet

io.github.GriffMurderPublished by GitHub account GriffMurderv0.2.1Updated Oct 29, 2026

Place US/CA phone calls and delegate tasks an AI agent cannot finish.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

TaskBullet lets an assistant hand work to a human virtual assistant or place a real US/Canada phone call, then read back the results.

What you can do
  • Check balance: read remaining VA hours and the calls wallet, including open holds
  • Delegate tasks: file a brief for a human virtual assistant, list recent tasks, read status and results, then confirm, cancel or reopen a delivery
  • Place calls: validate a call body and its hold, place one human phone call, read or update it, cancel it, and read the VA wrap-up summary
  • Track completion: poll task and call status or receive webhooks and callbacks
When to use it
Useful when an agent hits work it cannot finish itself, such as phone calls, 2FA or captcha steps, physical-world errands, subjective QA or long manual jobs, and the user is willing to pay for human help. Also relevant when a workflow needs a real outbound call to a US or Canada business.
Requirements
A TaskBullet account and an API key (tb_live_...) supplied as TASKBULLET_API_KEY or the x-api-key header; the key is created in the dashboard and shown once. Runs locally via npx with Node.js, or as the hosted remote endpoint. Prepaid VA hours for delegated tasks and a funded calls wallet for phone calls. Network access to the TaskBullet API.
Before you install
Real money is spent: delegated tasks bill tracked VA hours (15-minute rounding, capped by maxHours) and calls bill from the calls wallet at $2.50 for the first minute then $1 per minute, with a hold of about $6.50 for the default 5-minute call. confirm_task, cancel_task, reopen_task, place_call and cancel_call change real work and money, so the server asks for human confirmation. Never put passwords, OTP codes, recovery keys, cookies or API keys into briefs or calls. Calls are US/Canada only…

Installation

In SourceWeft

  1. Open TaskBullet in the dashboard and add it to a workspace.
  2. Connect x-api-key credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.GriffMurder%2Ftaskbullet/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "taskbullet": {
      "type": "http",
      "url": "https://taskbullet.com/api/agent-mcp",
      "headers": {
        "x-api-key": "<YOUR_API_KEY>"
      }
    }
  }
}

README

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:

text
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:

text
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:

text
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:

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

Decoded config:

json
{  "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:

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

Claude Code

bash
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:

text
/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:

json
{  "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.

ToolCallsNotes
get_balanceGET /api/v1/balanceRead-only. Hours and the calls wallet. Call this before proposing spend.
delegate_taskPOST /api/v1/delegateFiles a brief. Idempotency-Key required. Spends real hours after the customer starts it on Work.
list_tasksGET /api/v1/tasksRead-only. Up to 50 tasks. Filter includes cancelled.
get_taskGET /api/v1/tasks/{taskId}Read-only. Stop on completed, failed, or cancelled. awaitingCustomerConfirm means ask the human.
confirm_taskPOST /api/v1/tasks/{taskId}/confirmAccepts a delivery and settles tracked hours. Idempotency-Key required. Ask the human first.
cancel_taskPOST /api/v1/tasks/{taskId}/cancelReleases the hold and bills only tracked time. Idempotency-Key required. Ask the human first.
reopen_taskPOST /api/v1/tasks/{taskId}/reopenSends the delivery back. reason required. Idempotency-Key required. Ask the human first.
place_callPOST /api/v1/callsOne human call. US and Canada only. record_call must be false or omitted. Idempotency-Key required.
validate_callPOST /api/v1/calls/validateChecks the body. Creates nothing and places no hold. Returns hold_cents.
get_callGET /api/v1/calls/{id}Read-only. Includes needs_info or the final result.
update_callPATCH /api/v1/calls/{id}Fills missing fields while the call is needs_info.
cancel_callPOST /api/v1/calls/{id}/cancelAsks ops to cancel. Stays cancel_pending until ops confirms. A confirm before any dial refunds the hold. After the dial starts, the error is cancel_too_late and the call bills normally.
get_transcriptGET /api/v1/calls/{id}/transcript.txtVA wrap-up summary, not a recording. source is wrap_up_summary and recorded is false. Empty is transcript_not_ready. No dial is no transcript: call not placed. Cancel after the dial started is call_cancelled.

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:

ServerURLAuthWhat it can do
Agent (this package, and the hosted remote)https://taskbullet.com/api/agent-mcpx-api-key: tb_live_…get_balance, delegate_task, list_tasks, get_task, confirm_task, cancel_task, reopen_task, place_call, validate_call, get_call, update_call, cancel_call, get_transcript
Public site guidehttps://taskbullet.com/api/mcpnoneRead-only marketing info: services, pricing, hire vs job-seeker routing

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.

json
{  "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.

json
{  "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:

bash
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

VariableRequiredDefaultPurpose
TASKBULLET_API_KEYyes—tb_live_… key. npm and Cursor read it from the environment. The Claude plugin reads the prompt value only. Never logged or copied into tool results.
TASKBULLET_API_BASEnohttps://taskbullet.com/api/v1Override for staging
TASKBULLET_SOURCE_AGENTnomcp-clientAudit label stored on each brief
TASKBULLET_TRANSPORTnostdioSet to http to serve streamable HTTP
TASKBULLET_HTTP_HOSTno127.0.0.1Bind address. Non-loopback requires a token
TASKBULLET_HTTP_PORTno3000HTTP port
TASKBULLET_HTTP_TOKENwhen exposed—Local HTTP auth for npm and Cursor. The Claude plugin reads the prompt value only. Not the TaskBullet API key
TASKBULLET_HTTP_ALLOWED_ORIGINSnoloopback originsExtra browser Origin values, comma-separated

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.

Source: README.md at commit e6ee71b

Tools

13

get_balance

Get balance

Return remaining VA hours, capRoom, and whether a new cap can be filed. Also returns the calls wallet: balance_cents is spendable after open holds, wallet_cents is that amount plus holds_cents, and holds_cents is the sum of unsettled holds. addFundsUrl is POST /api/v1/billing/add-funds and this read does not create a Stripe session. canDelegate is false when hours are unavailable, when spendable hours are not above zero, or when open caps leave no room. canDelegate false while hoursRemaining is above zero means lower maxHours to capRoom or wait. It is not a buy-hours signal. Call this before proposing spend. Does not create a task.

Takes no parameters.

delegate_task

Delegate task

Call get_balance first, then confirm with the user before sending (real hours) unless they already said to send it. Delegate a task to a real human virtual assistant when the AI cannot complete it autonomously. Use this for phone calls, owner-authorized login or captcha steps (never send passwords or OTP), physical-world actions, subjective QA, manual data entry, or anything else outside the model's reach. Returns a taskId for tracking. The job is NOT started until the customer clicks Start on Work. The receipt status is awaiting_customer_start.

ParameterstitlerequireddueDatemaxHoursprioritywebhookUrldescriptionsourceAgentidempotencyKeyrequired

list_tasks

List delegated tasks

List recently delegated tasks for this account (id, title, status, short result). awaitingCustomerConfirm true means the delivery is done and the human must confirm, cancel, or reopen. amNote is the delivery note and deliverableLinks are https links from that note. pending and in_progress omit customer-cancelled jobs. cancelled is terminal.

Parametersstatus

get_task

Get delegated task

Get the current status, title, completion timestamp, and full result notes for a specific delegated task. awaitingCustomerConfirm true means ask the human, then confirm_task, cancel_task, or reopen_task. amNote is the AM or VA note. deliverableLinks lists https links. Stop when status is completed, failed, or cancelled. Customer cancel is cancelled, not pending or in_progress, and it does not send the completion webhook.

ParameterstaskIdrequired

confirm_task

Confirm task

Accept a delivery that is awaitingCustomerConfirm. Settles tracked hours, releases the board and ledger hold, and marks the task completed. If the human does not respond, the job confirms itself after 3 days. Ask the human first. Idempotency-Key is required. A repeat of the same key returns the same result.

ParameterstaskIdrequiredidempotencyKeyrequired

cancel_task

Cancel task

Customer never mind. Releases the hold and bills only tracked time. Does not send the completion webhook. Ask the human first. Idempotency-Key is required.

ParametersreasontaskIdrequiredidempotencyKeyrequired

reopen_task

Reopen task

Send a delivery that is awaitingCustomerConfirm back to the account manager with a reason. Does not settle hours. Ask the human first. Idempotency-Key is required.

ParametersreasonrequiredtaskIdrequiredidempotencyKeyrequired

place_call

Place call

Place one human phone call. The hold is the full call: the tier minimum for the first minute, then the per-minute rate for each additional minute. Default max_minutes is 5, so a tier 1 US or Canada call holds $6.50. Raise max_minutes on that call to hold more. record_call must be false or omitted. Only US and CA are live. A question is {"id","ask","type"?}: id up to 80 characters, ask up to 1000 characters, at most 20 questions. goal is at most 4000 characters. Idempotency key is required. Poll get_call, or pass callback_url. validate_call checks the body and places no hold.

Parametersgoalrequiredphonerequiredscriptpurposerequireddeadlinerequiredlanguageextensionquestionsrequiredmax_minutesrecord_callscript_modetime_window+12 more

validate_call

Validate call

Check a phone-call body without creating a call or placing a hold. Same fields as place_call, without idempotencyKey. A ready body includes hold_cents for the full call (tier 1 default $6.50 at 5 minutes) and whether recipient_timezone was inferred. valid stays true when spendable balance is below the hold. warnings then includes insufficient_balance with needed_cents and addFundsUrl.

Parametersgoalphonescriptpurposedeadlinelanguageextensionquestionsmax_minutesrecord_callscript_modetime_window+11 more

get_call

Get call

Read one human phone call, including needs_info missing_fields or the final result.

Parameterscall_idrequired

update_call

Update call

Fill missing_fields on a call in needs_info. Same result shapes as place_call.

Parametersgoalphonescriptcall_idrequiredpurposedeadlinelanguageextensionquestionsmax_minutesrecord_callscript_mode+12 more

cancel_call

Cancel call

Cancel a call. Status stays cancel_pending until ops confirms. A confirm before any dial refunds the hold and the status becomes cancelled. If the dial already started, the error is cancel_too_late and the call bills normally. A dial after a confirmed cancel is a full refund and the VA is unpaid.

Parameterscall_idrequired

get_transcript

Get transcript

Read the VA wrap-up summary for one call. This is not a recording. Once the call is wrap_up or completed, the result is that summary plus any question answers, with source wrap_up_summary and recorded false. Before a wrap-up summary exists, the result is transcript_not_ready. A call that ended without a dial (system failure or refund) is "no transcript: call not placed". A cancel after the dial started is call_cancelled. A recorded transcript may be a separate paid feature later and is not returned.

Parameterscall_idrequired

Version history

3
  1. v0.2.1LatestOct 21, 2026
  2. v0.2.0Oct 20, 2026
  3. v0.1.3Oct 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts