Mcp Agent Mail

Showing 25 of 40 from the live probe.

• Health Check

  Return basic readiness information for the Agent Mail server.

• Ensure Project

  Idempotently create or ensure a project exists for the given human key. When to use ----------- - First call in a workflow targeting a new repo/path identifier. - As a guard before registering agents or sending messages. How it works ------------ - Validates that `human_key` is an absolute directory path (the agent's working directory). - Computes a stable slug from `human_key` (lowercased, safe characters) so multiple agents can refer to the same project consistently. - Ensures DB row exist

• Register Agent

  Create or update an agent identity within a project and persist its profile to Git. When to use ----------- - At the start of a coding session by any automated agent. - To update an existing agent's program/model/task metadata and bump last_active. Semantics --------- - If `name` is omitted, a random adjective+noun name is auto-generated. - Reusing the same `name` updates the profile (program/model/task) and refreshes `last_active_ts`. - A `profile.json` file is written under `agents/<Name>/

• Deregister Agent

  Remove an agent from a project. Marks the agent as inactive and removes it from the active roster. Messages from/to the agent are preserved for audit but the agent can no longer send or receive new messages.

• Retire Agent

  Soft-delete an agent: mark it as retired so it stops accepting new messages while preserving message history. Retired agents are hidden from active agent lists but visible in 'all agents' views.

• Unretire Agent

  Restore a retired agent back to active status. The agent will resume accepting new messages.

• Archive Project

  Soft-delete a project: mark it as archived so it is hidden from active project lists. All messages are preserved and the project can be restored with unarchive_project.

• Unarchive Project

  Restore an archived project back to active status.

• Hard Delete Agent

  IRREVERSIBLY delete an agent and ALL associated data: messages sent by the agent, message recipient records, file reservations, agent links, window identities, and on-disk archive files (inbox, outbox, attachments). This is NOT soft-delete — data is permanently destroyed and cannot be recovered. Requires the confirmation parameter to be exactly 'I UNDERSTAND'.

• Hard Delete Project

  IRREVERSIBLY delete a project and ALL associated data: every agent, message, message recipient, file reservation, agent link, window identity, message summary, sibling suggestion, product link, and the entire on-disk project archive directory. This is NOT soft-delete — data is permanently destroyed and cannot be recovered. Requires the confirmation parameter to be exactly 'I UNDERSTAND'.

• Whois

  Return enriched profile details for an agent, optionally including recent archive commits. Discovery --------- To discover available agent names, use: resource://agents/{project_key} Agent names are NOT the same as program names or user names. Parameters ---------- project_key : str Project slug or human key. agent_name : str Agent name to look up (use resource://agents/{project_key} to discover names). include_recent_commits : bool If true, include latest commits touching the proj

• Create Agent Identity

  Create a new, unique agent identity and persist its profile to Git. How this differs from `register_agent` -------------------------------------- - Always creates a new identity with a fresh unique name (never updates an existing one). - `name_hint`, if provided, MUST be a valid adjective+noun combination and must be available, otherwise an error is raised. Without a hint, a random adjective+noun name is generated. CRITICAL: Agent Naming Rules ----------------------------- - Agent names MUST

• List Window Identities

  List active window identities for a project. Returns all non-expired window identities with their display names, last activity timestamps, and age. Parameters ---------- project_key : str Project identifier. Returns ------- dict { identities: [{ id, window_uuid, display_name, created_ts, last_active_ts, expires_ts }] }

• Rename Window

  Update the display name of a window identity. Parameters ---------- project_key : str Project identifier. window_uuid : str The UUID of the window identity to rename. new_display_name : str New display name (must be a valid adjective+noun agent name). Returns ------- dict Updated window identity record.

• Expire Window

  Mark a window identity as expired. Parameters ---------- project_key : str Project identifier. window_uuid : str The UUID of the window identity to expire. Returns ------- dict { window_uuid, expired: bool, expired_at }

• Send Message

  Send a Markdown message to one or more recipients and persist canonical and mailbox copies to Git. Discovery --------- To discover available agent names for recipients, use: resource://agents/{project_key} Agent names are NOT the same as program names or user names. What this does -------------- - Stores message (and recipients) in the database; updates sender's activity - Writes a canonical `.md` under `messages/YYYY/MM/` - Writes sender outbox and per-recipient inbox copies - Optionally conv

• Purge Old Messages

  Delete messages older than the configured retention period. Defaults to retention_max_age_days from config (180 days). Returns count of messages purged.

• Reply Message

  Reply to an existing message, preserving or establishing a thread. Behavior -------- - Inherits original `importance` and `ack_required` flags - `thread_id` is taken from the original message if present; otherwise, the original id is used - Subject is prefixed with `subject_prefix` if not already present - Defaults `to` to the original sender if not explicitly provided Parameters ---------- project_key : str Project identifier. message_id : int The id of the message you are replying to

• Request Contact

  Request contact approval to message another agent. Creates (or refreshes) a pending AgentLink and sends a small ack_required intro message. Discovery --------- To discover available agent names, use: resource://agents/{project_key} Agent names are NOT the same as program names or user names. Parameters ---------- project_key : str Project slug or human key. from_agent : str Your agent name (must be registered in the project). to_agent : str Target agent name (use resource://agents

• Respond Contact

  Approve or deny a contact request.

• List Contacts

  List contact links for an agent in a project.

• Set Contact Policy

  Set contact policy for an agent: open | auto | contacts_only | block_all.

• Fetch Inbox

  Retrieve recent messages for an agent without mutating read/ack state. Filters ------- - `urgent_only`: only messages with importance in {high, urgent} - `since_ts`: ISO-8601 timestamp string; messages strictly newer than this are returned - `limit`: max number of messages (default 20) - `include_bodies`: include full Markdown bodies in the payloads - `topic`: filter to messages with this topic tag Usage patterns -------------- - Poll after each editing step in an agent loop to pick up coordin

• Fetch Topic

  Fetch all messages in a project with a given topic tag, regardless of recipient. Parameters ---------- project_key : str Project identifier. topic_name : str The topic tag to filter by (case-insensitive). limit : int Max number of messages to return (default 50). include_bodies : bool Include full Markdown bodies in the payloads (default true). since_ts : Optional[str] ISO-8601 timestamp; only messages newer than this are returned. Returns ------- list[dict] Each messag

• Mark Message Read

  Mark a specific message as read for the given agent. Notes ----- - Read receipts are per-recipient; this only affects the specified agent. - This does not send an acknowledgement; use `acknowledge_message` for that. - Safe to call multiple times; later calls return the original timestamp. Idempotency ----------- - If `mark_message_read` has already been called earlier for the same (agent, message), the original timestamp is returned and no error is raised. Returns ------- dict { message