MCP Reference
Complete MCP tool reference with parameters and return types
The MCP server runs at /mcp/sse using Server-Sent Events transport. All requests require the bee.mcp.api_key for authentication.
Worker Management
list_workers
List all registered workers.
Parameters: None
Returns: Array of worker objects with id, name, description, memory, work_dir, status, created_at, updated_at.
get_worker
Get a single worker by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
worker_id | string | Yes | Worker UUID |
create_worker
Create a new worker.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Worker display name |
description | string | No | Worker purpose |
memory | string | No | Initial persistent memory |
work_dir | string | No | Custom working directory |
update_worker
Update worker properties (patch semantics).
| Parameter | Type | Required | Description |
|---|---|---|---|
worker_id | string | Yes | Worker UUID |
name | string | No | New name |
description | string | No | New description |
memory | string | No | New memory content |
delete_worker
Delete a worker.
| Parameter | Type | Required | Description |
|---|---|---|---|
worker_id | string | Yes | Worker UUID |
delete_work_dir | boolean | No | Also delete working directory |
Task Management
create_task
Create a task assigning a worker to handle a user instruction from a message.
| Parameter | Type | Required | Description |
|---|---|---|---|
message_id | string | Yes | Originating message ID |
worker_id | string | Yes | Target worker UUID |
instruction | string | Yes | Task instruction |
type | string | Yes | immediate, countdown, or scheduled |
scheduled_at | integer | Conditional | Unix ms, required for countdown (must be >= now+5s) |
cron_expr | string | Conditional | 5-field cron expression, required for scheduled |
list_tasks
List tasks filtered by message_id, session_key, and/or worker_id. message_id and session_key are mutually exclusive; at least one of message_id, session_key, or worker_id is required.
| Parameter | Type | Required | Description |
|---|---|---|---|
message_id | string | No | Filter by message (mutually exclusive with session_key) |
session_key | string | No | Filter by session (mutually exclusive with message_id) |
worker_id | string | No | Filter by worker; can be combined with session_key |
status | string | No | Filter by status, supports comma-separated values (e.g. pending,running) |
type | string | No | Filter by type, supports comma-separated values (e.g. immediate,countdown) |
cancel_task
Cancel a pending or scheduled task.
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | Yes | Task UUID |
mark_task_complete
Mark a task as completed.
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | Yes | Task UUID |
Messaging
send_message
Send a message to the user on the originating platform. Supports sending media files (images, documents, audio, video) by providing a local file path.
| Parameter | Type | Required | Description |
|---|---|---|---|
message_id | string | Yes | Originating platform message ID (resolves platform and reply context) |
content | string | No | Text content to send (required unless media_path is provided) |
media_path | string | No | Local file path to upload and send as media |
Session Management
clear_session
Cancel all active tasks (terminating running worker processes), clear dispatcher queues, and reset all session contexts for the given session.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_key | string | Yes | Session identifier |
force | boolean | No | Skip confirmation when multiple workers are linked (default false) |
list_session_contexts
List workers with active contexts in a session.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_key | string | Yes | Session identifier |
clear_worker_session
Reset a specific worker's Claude Code session context.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_key | string | Yes | Session identifier |
worker_id | string | Yes | Worker UUID |
Memory
save_memory
Save or update a memory entry.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string | Yes | global or session key |
key | string | Yes | Memory key |
value | string | Yes | Memory value |
get_memory
Retrieve memory entries.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string | Yes | global or session key |
key | string | No | Specific key (omit for all entries in scope) |
delete_memory
Delete a memory entry.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string | Yes | global or session key |
key | string | Yes | Memory key |
Monitoring
get_worker_status
View worker status and pending task count.
| Parameter | Type | Required | Description |
|---|---|---|---|
worker_id | string | Yes | Worker UUID |
get_system_overview
Get system-wide statistics. No parameters.
Returns: Worker count by status, total tasks by status, recent executions.
list_bee_executions
View bee coordinator execution history.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | int | No | Max results (default 10) |