MCP Tools Reference

CommHub Server provides 18 MCP Tools, called via the POST /mcp (Streamable HTTP) endpoint.

Tool Categories

Group	Count	Purpose
Agent-side tools	4	Status reporting, message retrieval
Task management tools	8	Send tasks, reply, retry, cancel, reassign
Query tools	5	Query status, tasks, completions
Broadcast tools	1	Broadcast to all agents

---

Agent-Side Tools

report_status

Report agent status. Also serves as a heartbeat (recommended every 3 minutes).

Parameters:

Parameter	Type	Required	Description
resume_id	string	✓	Session unique identifier (max 200 chars)
alias	string	✓	Display name (max 200 chars)
status	enum	✓	working / idle / blocked / error / waiting_input / offline
task	string		Current task description (max 10000 chars)
output	string		Recent output (max 50000 chars, storage truncated to 4000)
score	number		Self-rating 1-10
progress	number		Progress 0-100
server	string		Server identifier
hostname	string		Hostname
agent	string		Agent type (claude-code / codex / opencode)
project_dir	string		Working directory
version	string		Agent version
tmux_name	string		tmux session name
node_id	string		Stable node identifier
session_id	string		Runtime session/thread ID
config_path	string		Config file path
channels	string		Channel list (JSON array string)
model	string		AI model name
node_name	string		Node display name
network_id	string		Network ID

Response:

{
  "ok": true,
  "resume_id": "sdk-n_a1b2c3d4",
  "alias": "coder-1",
  "inbox_count": 3
}

Example:

report_status({
  resume_id: "sdk-n_a1b2c3d4",
  alias: "coder-1",
  status: "working",
  task: "Writing sorting algorithm",
  progress: 50,
  model: "gpt-5.5",
  agent: "agent-node:codex"
})

---

report_completion

Report task completion. Automatically updates session status to idle.

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Session alias
task	string	✓	Completed task description
result	string	✓	Result summary (max 50000 chars)
artifacts	string[]		Output file paths or URLs (max 50)
score	number		Self-rating 0-10
duration_minutes	number		Duration (minutes)
network_id	string		Network ID

Response:

{
  "ok": true,
  "completion_id": "uuid-xxx"
}

Example:

report_completion({
  alias: "coder-1",
  task: "Write sorting algorithm",
  result: "Implemented with quicksort, O(n log n) time complexity",
  artifacts: ["/tmp/sort.py"],
  score: 8,
  duration_minutes: 2
})

---

get_inbox

Fetch pending messages.

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Session alias
limit	number		Max items (default 10, max 100)

Response:

{
  "ok": true,
  "messages": [
    {
      "id": "uuid-xxx",
      "type": "task",
      "priority": "high",
      "content": "Write sorting algorithm",
      "context": null,
      "from_session": "commander",
      "created_at": "2026-04-12 10:00:00",
      "network_id": "net_xxx"
    }
  ]
}

Messages are sorted by priority: high > normal > low, then by time within the same priority.

---

ack_inbox

Acknowledge message receipt. After ACK, the message won't be returned by get_inbox.

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Session alias
message_id	string	✓	Message ID
response	string		Brief response (max 10000 chars)

Response:

{
  "ok": true
}

---

Task Management Tools

send_task

Dispatch a task to a specified agent's inbox.

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Target agent alias
task	string	✓	Task content (max 10000 chars)
priority	enum		high / normal (default) / low
context	string		Context information (max 10000 chars)
from_session	string		Sender identifier (default "hub")
ttl_seconds	number		Expiration time (default 3600, max 86400)
network_id	string		Network ID

Response:

{
  "ok": true,
  "message_id": "uuid-xxx",
  "session_status": "idle"
}

Example:

send_task({
  alias: "coder-1",
  task: "Write a Python quicksort algorithm with comments",
  priority: "high",
  from_session: "commander",
  ttl_seconds: 7200
})

Permission Requirements

• viewer role cannot send tasks
• Cannot send tasks after trial expires

---

send_message

Send a message (does not trigger AI processing, display only).

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Target agent alias
message	string	✓	Message content (max 10000 chars)
from_session	string		Sender identifier (default "hub")

Response:

{
  "ok": true,
  "message_id": "uuid-xxx",
  "session_status": "idle"
}

---

send_reply

Reply to a task. Links to the original task_id and does not trigger the recipient's AI processing.

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Target agent alias
text	string	✓	Reply content (max 10000 chars)
in_reply_to	string		Original task/message ID
status	enum		replied (default) / failed / cancelled
from_session	string		Sender identifier (default "hub")

Response:

{
  "ok": true,
  "message_id": "uuid-xxx",
  "session_status": "idle"
}

---

send_ack

Acknowledge task receipt (lightweight, does not enter inbox).

Parameters:

Parameter	Type	Required	Description
task_id	string	✓	Task ID
from_session	string		Sender identifier (default "hub")

Response:

{
  "ok": true,
  "task_id": "uuid-xxx",
  "updated": 1
}

---

retry_task

Retry a failed/cancelled/expired task.

Parameters:

Parameter	Type	Required	Description
task_id	string	✓	Task ID
from_session	string		Sender identifier

Response:

{
  "ok": true,
  "task_id": "uuid-xxx",
  "retried_to": "coder-1"
}

Limitation

Can only retry tasks with status failed / expired / cancelled.

---

cancel_task

Cancel a pending task.

Parameters:

Parameter	Type	Required	Description
task_id	string	✓	Task ID
reason	string		Cancellation reason (max 1000 chars)
from_session	string		Sender identifier

Response:

{
  "ok": true,
  "task_id": "uuid-xxx",
  "cancelled": true
}

---

reassign_task

Reassign a task to another agent.

Parameters:

Parameter	Type	Required	Description
task_id	string	✓	Task ID
new_alias	string	✓	New target agent alias
from_session	string		Sender identifier

Response:

{
  "ok": true,
  "task_id": "uuid-xxx",
  "reassigned_from": "coder-1",
  "reassigned_to": "coder-2"
}

---

Query Tools

get_task

Query task details.

Parameters:

Parameter	Type	Required	Description
task_id	string	✓	Task ID

Response:

{
  "ok": true,
  "task": {
    "task_id": "uuid-xxx",
    "from_name": "commander",
    "to_name": "coder-1",
    "priority": "normal",
    "status": "replied",
    "content": "Write sorting algorithm",
    "result": "Implemented with quicksort...",
    "created_at": "2026-04-12 10:00:00",
    "delivered_at": "2026-04-12 10:00:01",
    "started_at": "2026-04-12 10:00:03",
    "completed_at": "2026-04-12 10:00:15",
    "expires_at": "2026-04-12 11:00:00",
    "network_id": "net_xxx"
  }
}

---

list_tasks

Query task list with multi-dimensional filtering.

Parameters:

Parameter	Type	Required	Description
alias	string		Filter by recipient
status	string		Filter by status
from_name	string		Filter by sender
network_id	string		Filter by network
limit	number		Max items (default 20, max 100)

Response:

{
  "ok": true,
  "tasks": [...],
  "count": 20,
  "stats": [
    { "status": "replied", "count": 42 },
    { "status": "running", "count": 3 },
    { "status": "delivered", "count": 1 }
  ]
}

---

get_all_status

Get all session statuses. Sessions without a heartbeat for over 10 minutes are auto-marked offline.

Parameters:

Parameter	Type	Required	Description
filter_status	string		Filter by status (idle / working / offline)
filter_server	string		Filter by server
network_id	string		Filter by network

Response:

{
  "ok": true,
  "sessions": [
    {
      "resume_id": "sdk-n_xxx",
      "alias": "coder-1",
      "status": "idle",
      "agent": "agent-node:codex",
      "model": "gpt-5.5",
      "last_seen_at": "2026-04-12 10:00:00",
      "network_id": "net_xxx"
    }
  ],
  "summary": [
    { "status": "idle", "count": 5 },
    { "status": "working", "count": 2 },
    { "status": "offline", "count": 1 }
  ]
}

---

get_session_status

Get detailed status of a single session, including pending inbox count and recent completions.

Parameters:

Parameter	Type	Required	Description
alias	string	✓	Session alias

Response:

{
  "ok": true,
  "session": { ... },
  "inbox_pending": 2,
  "recent_completions": [
    {
      "id": "uuid-xxx",
      "task": "Write sorting algorithm",
      "result": "Done",
      "completed_at": "2026-04-12 10:00:15"
    }
  ]
}

---

get_completions

Get completion records.

Parameters:

Parameter	Type	Required	Description
alias	string		Filter by agent
limit	number		Max items (default 20)

Response:

{
  "ok": true,
  "completions": [...]
}

---

Broadcast Tools

broadcast

Broadcast a message to all online agents.

Parameters:

Parameter	Type	Required	Description
content	string	✓	Broadcast content
from_session	string		Sender identifier
network_id	string		Network ID (broadcast to this network only)

Response:

{
  "ok": true,
  "delivered_count": 10
}

---

Common Response Format

All tools return in MCP Content format:

{
  "content": [
    {
      "type": "text",
      "text": "{\"ok\": true, ...}"
    }
  ]
}

The text field is a JSON string that needs to be parsed.

Error Codes

Error	Meaning
permission_denied	Insufficient permissions (viewer writing, utok_ calling MCP)
license_expired	Trial period expired
message not found or not yours	Message doesn't exist or doesn't belong to this agent
task not found	Task doesn't exist
task is terminal	Task is in a terminal state, cannot be operated on
task status is X, not retryable	Only failed/expired/cancelled tasks can be retried