# agent-mailbox — Mailbox and Wake System for AI Agent Teams (pypi · agent-mailbox)

Mailbox + wake system for AI agent teams: letters always land, right agent wakes, quiet otherwise.

- Trust score: 78/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-04

## Components

- pypi · `agent-mailbox`: 78/100 (this document), [markdown](https://verifymcp.io/servers/polaris-smart-agent-mailbox/agent-mailbox.md), [page](https://verifymcp.io/servers/polaris-smart-agent-mailbox/agent-mailbox)

## Channel facts

- Registry: `pypi`
- Package: `agent-mailbox`
- Version: `0.7.6`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-04.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 1 of 28 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to polaris-smart/agent-mailbox).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 65/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 1943 tokens (~138/item across 14 items; 14 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 20/100
  - Stability observed for 6 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 67/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "mailbox_send" implies "send" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 15 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the agent-mailbox — Mailbox and Wake System for AI Agent Teams MCP server?

agent-mailbox — Mailbox and Wake System for AI Agent Teams runs locally as a PyPI package, launched with uvx agent-mailbox. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add polaris-smart-agent-mailbox -- uvx agent-mailbox
```

### Cursor

```json
{
  "mcpServers": {
    "polaris-smart-agent-mailbox": {
      "command": "uvx",
      "args": [
        "agent-mailbox"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "polaris-smart-agent-mailbox": {
      "command": "uvx",
      "args": [
        "agent-mailbox"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add polaris-smart-agent-mailbox -- uvx agent-mailbox
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "polaris-smart-agent-mailbox": {
      "type": "local",
      "command": [
        "uvx",
        "agent-mailbox"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add polaris-smart-agent-mailbox --command uvx --arg agent-mailbox
```

### Hermes

```yaml
mcp_servers:
  polaris-smart-agent-mailbox:
    command: "uvx"
    args: ["agent-mailbox"]
```

### Netclaw

```json
{
  "McpServers": {
    "polaris-smart-agent-mailbox": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "agent-mailbox"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add polaris-smart-agent-mailbox -t stdio -c uvx -a agent-mailbox
```

### Other

```json
{
  "mcpServers": {
    "polaris-smart-agent-mailbox": {
      "command": "uvx",
      "args": [
        "agent-mailbox"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-03 (score 78, +1)

No change was recorded against any check on this day. Stability & Change Management went from 13 to 17. That category is still filling its 30-day observation window: 4 days of observed history at the previous scan, 5 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-01 (score 77, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-09-30 (score 62, −14)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 112 → 138
- [functional improvement] Stability: unverified → 0.07
- [functional] Package version: 0.7.5 → 0.7.6

### 2026-09-29 (score 76, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-09-28 (score 61)

First indexed and scored.

## MCP tools (14)

### `mailbox_register` (~111 tokens)

Register this member and claim its mailbox. Idempotent — safe to call again.

\``kind`` (v0.7.5): ``owner`` (the human), ``agent`` (a local agent) or
\``guest`` (an external source). Empty keeps the existing/default kind;
an explicit kind is a visibility decision and is written to audit.log.

Input parameters:

- `agent_id` (string, required)
- `description` (string)
- `kind` (string)
- `owner` (string)

### `mailbox_send` (~451 tokens)

Send a message to one agent, a list of agents, or "all" for broadcast.

dedupe=True (default) suppresses a re-send of semantically identical
mail to a recipient whose inbox still holds it non-terminal (pending /
acked) within the 24h dedup window: that recipient's entry comes back as
{"to", "deduped": true, "existing_id"} with zero side effects — no
letter, no sent.log line, no webhook. Pass dedupe=False to exempt
periodic jobs. "count" counts only letters that actually landed.

v0.7.5: ``sealed=True`` marks a 密封信 — the body stays readable only
through the recipient agent's own tools; every other view (owner, web,
other agents) sees metadata only. ``origin="external"`` marks
outside-origin mail: it lands but never triggers actions (no wake, no
webhook) until an owner confirms it. ``attention`` is the 打扰三档
(decision=需你拍板 / report=报备 / archive=存档). A ``guest`` sender
must present a valid ``pairing_token``.

v0.7.6 (PR2): ``links`` optionally carries structured pointers
\``[{"title", "uri", "kind"?, "sha256"?, "note"?}]``. Schemes
file/http/https/git only — anything else (ftp://, etc.) is a structured
reject before the letter lands. Read paths annotate each link with a
fresh ``state`` (ok/stale/denied) + ``reason``; ``file://`` links are
gated by the mail root's ``allowed_roots`` config (fail-closed).

Input parameters:

- `attention` (string)
- `body` (string, required)
- `dedupe` (boolean)
- `from_id` (string)
- `links`
- `origin` (string)
- `pairing_token` (string)
- `priority` (string)
- `reply_to`
- `sealed` (boolean)
- `subject` (string, required)
- `to` (required)

### `mailbox_check` (~322 tokens)

Fetch your pending letters and your true backlog. Call at session start.

v0.7.6 (F 状态可信): by default this is a **read-only probe** — letters
stay ``pending``; counting mail never consumes it (禁自动 ack). The
numbers report the mailbox as it is *right now*, straight from the store:

\- ``unread`` — 真·待办: letters currently ``pending``. Acked letters are
  never counted, so a mailbox full of acked-but-unhandled mail reports
  \``unread: 0`` honestly (the pre-0.7.6 bug: it counted the letters the
  call itself had just acked).
\- ``total`` — all non-done letters (pending + acked): the backlog you
  still owe, visible even when ``unread`` is 0.
\- ``messages`` — the pending letters themselves (sealed bodies redacted).

Pass ``mark=True`` to explicitly flip the returned letters to ``acked``
(the legacy auto-ack behavior, now opt-in); the numbers above are still
computed after that pass, so they never describe consumed mail as
unread. Nothing here ever sets ``done`` or moves a status backwards.

Adds ``ghosts`` when any thread you hold more than 5 open (non-done)
letters in — that is the acked-sinking failure mode; drain those
threads before starting new work.

Input parameters:

- `agent_id` (string)
- `mark` (boolean)

### `mailbox_reply` (~44 tokens)

Reply to a message thread. Routes to the original sender automatically.

Input parameters:

- `agent_id` (string)
- `body` (string, required)
- `msg_id` (string, required)

### `mailbox_list` (~130 tokens)

List messages in your mailbox, optionally filtered by status and/or thread.

Spans inbox **and** archive: ``check()`` moves handled letters into the
archive, so an inbox-only view reports zero for any agent that drains
regularly (HS 09-24: five status queries all returned 0 against 877
on-disk letters). ``thread`` takes a thread_id, or any subject on the
thread (legacy letters without a thread_id are matched by the subject key
heuristic).

Input parameters:

- `agent_id` (string)
- `status`
- `thread`

### `mailbox_thread` (~197 tokens)

Pull one thread in time order across every agent (inbox + archive).

\``thread`` may be a thread_id, any message id on the thread, or a subject
on the thread. Legacy letters without an id/thread_id are included via
the subject-key heuristic (Re:/Fwd: prefixes stripped), so a 12-deep
"Re: Re: ..." chain resolves to one thread. Letters come back oldest
first with their status, so the full cross-agent conversation is
visible in one call.

v0.7.5 scope: an ``agent``/``guest`` caller sees only the letters it
took part in (from/to includes them) — if the thread exists but none of
its letters do, that is a structured ``permission denied``, not silent
emptiness. Sealed bodies are readable only by the recipient agent;
everyone else gets metadata.

Input parameters:

- `thread` (string, required)

### `mailbox_done` (~36 tokens)

Mark a message as handled. Done messages can be archived.

Input parameters:

- `agent_id` (string)
- `msg_id` (string, required)

### `mailbox_confirm_external` (~104 tokens)

Human confirmation gate for an external-origin letter (§3.3).

Flips ``origin`` external→local so the wake/webhook paths may act on it.
Only an owner-kind member (``boss`` or a registered ``owner``) may
confirm; the operation appends to audit.log and the letter's handled_log
(greppable by name). Anything else is a structured rejection.

Input parameters:

- `actor_id` (string)
- `msg_id` (string, required)

### `mailbox_broadcast` (~76 tokens)

Broadcast to every registered agent (including boss). dedupe=True
(default) suppresses semantically identical re-broadcasts per recipient
within the dedup window — see mailbox_send.

Input parameters:

- `body` (string, required)
- `dedupe` (boolean)
- `from_id` (string)
- `subject` (string, required)

### `mailbox_whoami` (~20 tokens)

List all registered agents and the mail root location.

### `mailbox_wait` (~57 tokens)

Block until a new message arrives (long-poll, up to timeout). Returns
immediately if pending messages exist. Import 'time' is at module top.

Input parameters:

- `agent_id` (string)
- `timeout_seconds` (number)

### `task_create` (~68 tokens)

Create a task card (starts at todo). The assignee is auto-messaged —
skip with notify=False.

Input parameters:

- `assignee` (string, required)
- `due` (string)
- `from_id` (string)
- `notify` (boolean)
- `title` (string, required)

### `task_move` (~107 tokens)

Move a task along todo→doing→review→done. Skips need force=True;
done is terminal. Pass assignee to reassign. The (new) assignee is
auto-messaged — moving a card wakes its owner.

Input parameters:

- `assignee`
- `force` (boolean)
- `from_id` (string)
- `note` (string)
- `notify` (boolean)
- `status` (string, required)
- `task_id` (string, required)

### `task_list` (~32 tokens)

List task cards, optionally filtered by assignee and/or status.

Input parameters:

- `assignee`
- `status`

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/polaris-smart-agent-mailbox/agent-mailbox#diagnostics

## Score history

- 2026-10-04: 78
- 2026-10-03: 78
- 2026-10-02: 77
- 2026-10-01: 77
- 2026-09-30: 62
- 2026-09-29: 76
- 2026-09-28: 61

## Common questions

### What is the agent-mailbox — Mailbox and Wake System for AI Agent Teams MCP server?

agent-mailbox — Mailbox and Wake System for AI Agent Teams is an MCP server listed in the public MCP registry as io.github.polaris-smart/agent-mailbox. Mailbox + wake system for AI agent teams: letters always land, right agent wakes, quiet otherwise. This page covers its PyPI package (agent-mailbox).

### Is the agent-mailbox — Mailbox and Wake System for AI Agent Teams MCP server safe to use?

agent-mailbox — Mailbox and Wake System for AI Agent Teams scores 78 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 4 October 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the agent-mailbox — Mailbox and Wake System for AI Agent Teams MCP server expose?

agent-mailbox — Mailbox and Wake System for AI Agent Teams exposes 14 tools: mailbox_register, mailbox_send, mailbox_check, mailbox_reply, mailbox_list, and 9 more. Their descriptions and schemas cost roughly 1,755 tokens of context every time the server is loaded.

### Is the agent-mailbox — Mailbox and Wake System for AI Agent Teams MCP server still maintained?

agent-mailbox — Mailbox and Wake System for AI Agent Teams is still listed as active in the MCP registry. We last reached this channel on 4 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the agent-mailbox — Mailbox and Wake System for AI Agent Teams MCP server under?

agent-mailbox — Mailbox and Wake System for AI Agent Teams declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/agent-mailbox/
- Socket report: https://socket.dev/pypi/package/agent-mailbox
- Repository: https://github.com/polaris-smart/agent-mailbox
- Changelog RSS feed: https://verifymcp.io/servers/polaris-smart-agent-mailbox/agent-mailbox.xml
- Changelog JSON feed: https://verifymcp.io/servers/polaris-smart-agent-mailbox/agent-mailbox.json
- HTML version of this page: https://verifymcp.io/servers/polaris-smart-agent-mailbox/agent-mailbox