@taskbullet/mcp-server

@taskbullet/mcp-server

MCP server for AI agent → human virtual assistant handoff. When your AI agent hits a task it can't complete (phone calls, 2FA-gated logins, physical-world actions, subjective QA), delegate it to a real human VA via the TaskBullet Agent API.

What this is

A Model Context Protocol server that gives any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, Continue, etc.) native tools to delegate tasks to a real human virtual assistant.

LLMs are brilliant at thinking. They are useless at:

• Making phone calls
• Logging into 2FA / captcha-gated portals
• Subjective quality review ("does this look good?")
• Physical-world actions (mail, deliveries, in-person errands)
• Long-tail manual data entry

This server bridges that gap. Call get_balance first, confirm spend, then delegate_task — a TaskBullet virtual assistant picks it up.

Grok / Cursor / cloud agents: use the hosted MCP instead of this npx package. Cloud bots cannot run npx.

https://taskbullet.com/api/agent-mcp

Header: x-api-key: tb_live_… (API key only — not OAuth). Same four tools as below.

Tools exposed

Tool	Description
get_balance	Remaining hours and whether delegate_task will be accepted. Call this first.
delegate_task	Send a new task to a human virtual assistant. Returns a taskId.
list_tasks	List recently delegated tasks, optionally filtered by status.
get_task	Poll the status and result of a specific task by taskId.

There is no cancel_task yet.

Install (laptop stdio)

You need a TaskBullet account and an API key.

• Sign up / log in at taskbullet.com
• Generate an API key at taskbullet.com/dashboard/settings/api-keys
• Wire up the server in your MCP client config (see below), or point Grok/Cursor at the hosted URL above.

Configure in Claude Desktop

Edit claude_desktop_config.json (location varies by OS — see Anthropic's docs):

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

Restart Claude Desktop. You'll see the TaskBullet tools appear in the tools panel.

Configure in Cursor / Continue / other MCP clients

Any client that supports MCP servers via stdio will work. Point it at:

command: npx
args:    -y @taskbullet/mcp-server
env:     TASKBULLET_API_KEY=tb_live_...

Configure in custom agent frameworks

For LangChain, CrewAI, AutoGen, or custom orchestration, you can either:

• Use this MCP server directly via an MCP client library, OR
• Call the underlying TaskBullet REST API (or the OpenAPI spec) directly.

Example: Claude using delegate_task

You: Find me a flight from SFO to Austin next Tuesday under $300. If you can't book it directly, have someone book it for me.

Claude: I found a Delta flight at 8:15 AM for $278 but it requires phone booking due to a fare class restriction. Let me delegate the booking to your TaskBullet assistant.

[calls delegate_task with title: "Book Delta DL1423 SFO→AUS Tue Jun 3, 8:15 AM, $278. Use my saved AmEx ending 4321. Email confirmation to me."]

Booked task atask_a3f9c2d1. Your assistant will pick this up and you'll get an email when it's confirmed.

Environment variables

Variable	Required	Default	Purpose
TASKBULLET_API_KEY	✅	—	Your tb_live_... API key
TASKBULLET_API_BASE	❌	https://taskbullet.com/api/v1	Override for self-hosted or staging
TASKBULLET_SOURCE_AGENT	❌	mcp-client	Audit label for which agent originated the request

How task completion is delivered back

You have two options:

• Poll — your agent calls get_task periodically until status === "completed".
• Webhook — pass webhookUrl to delegate_task and TaskBullet POSTs a signed payload when the VA finishes. (See the webhook docs.)

How TaskBullet works under the hood

• You pre-purchase a Bucket of Hours (no monthly retainer).
• Hours roll over for 90 days so bursty AI workloads don't waste capacity.
• Tasks delegated through this MCP server route to your matched, dedicated virtual assistant.
• You only spend bucket hours when the VA is actually working on a delegated task — the API itself is free.

Learn more at taskbullet.com.

License

MIT — see LICENSE.

Keywords: mcp server, model context protocol, claude, anthropic, ai agent handoff, human-in-the-loop, virtual assistant, AI delegation, autonomous agent, llm tools, agentic workflow