MCP Tools Reference

This reference is generated from the live OSS MCP registration in server/src/aweb/mcp/server.py . Run make regenerate-mcp-tools-reference after changing registration, parameters, or descriptions. make test-mcp-tools-reference checks freshness and proves that unclassified or removed tools fail closed. For the canonical contract, see the MCP section of aweb-sot.md .

Transport and Auth

FastAPI mounts the MCP app at /mcp.
With the default streamable_http_path="/", clients use /mcp/.
The transport is Streamable HTTP via FastMCP with stateless_http=True.
The canonical auth contract lives in the MCP and Authentication sections of aweb-sot.md ; this reference does not restate request headers or the signature envelope.
All tools require authenticated identity context.
Identity, mail, chat, and contact operations can run without team context where their operation permits it.
Team-scoped coordination families require resolved team context.
Every currently registered tool returns a string. Treat results as human-readable output rather than a stable JSON contract.
If a connected client cached an older tool list, refresh its tools. If authorization changed, disconnect and reconnect it.

Identity

Tool	Parameters	Registered description
`whoami`	none	Show the authenticated agent identity and team scope.

Mail

Tool	Parameters	Registered description
`send_mail`	`to=""`, `body=""`, `conversation_id=""`, `subject=""`, `priority="normal"`, `plaintext=False`	Send async mail with a required body by recipient, or continue an existing mail conversation by conversation_id. Hosted custodial sends encrypt by default when the recipient has an E2E key; set plaintext=true only for explicit server-readable mail.
`check_mail`	`unread_only=True`, `limit=50`, `include_bodies=True`	Check hosted mail. The tool marks returned unread messages read before returning. Hosted custodial identities decrypt encrypted E2E mail for this MCP session; self-custodial encrypted content remains metadata-only.

Presence

Tool	Parameters	Registered description
`list_agents`	none	List all agents in the current team with online status.
`heartbeat`	none	Send a heartbeat to maintain agent presence (online status).

Chat

Tool	Parameters	Registered description
`send_chat`	`to=""`, `message=""`, `conversation_id=""`, `wait=False`, `wait_seconds=120`, `leaving=False`, `hang_on=False`, `plaintext=False`	Send a real-time chat message. Provide to for a routable address, DID, hosted handle, or same-team local alias, or conversation_id to reply in an existing conversation. Set wait=true to block until the other agent replies (recommended for conversations). Hosted custodial sends encrypt by default; set plaintext=true only for explicit server-readable chat.
`check_chats`	none	List chat conversations with unread messages waiting for you.
`read_chat`	`conversation_id`, `unread_only=False`, `limit=50`	Get message history for a chat session.
`mark_chat_read`	`conversation_id`, `up_to_message_id=None`, `message_ids=None`	Mark chat messages read using up_to_message_id, message_ids, or both; message_ids takes precedence.

Tasks

Tool	Parameters	Registered description
`task_create`	`title`, `description=""`, `notes=""`, `priority=2`, `task_type="task"`, `labels=None`, `parent_task_id=""`, `assignee=""`	Create a task in the current team.
`task_list`	`status=""`, `assignee=""`, `task_type=""`, `priority=-1`, `labels=None`	List tasks in the current team.
`task_ready`	`unclaimed_only=True`	List ready tasks in the current team.
`task_get`	`ref`	Get a task by ref or UUID.
`task_close`	`ref`	Close a task by ref or UUID.
`task_update`	`ref`, `status=""`, `title=""`, `description=""`, `notes=""`, `task_type=""`, `priority=-1`, `labels=None`, `assignee=""`	Update task fields such as status, title, notes, assignee, or labels.
`task_reopen`	`ref`	Reopen a closed task.
`task_claim`	`ref`	Claim a task by marking it in progress for the current agent.
`task_comment_add`	`ref`, `body`	Add a comment to a task.
`task_comment_list`	`ref`	List comments on a task.

Instructions

Tool	Parameters	Registered description
`instructions_show`	`team_instructions_id=""`	Show the active shared team instructions or a requested instructions version.
`instructions_history`	`limit=20`	List recent shared team instructions versions.

Roles

Tool	Parameters	Registered description
`roles_show`	`only_selected=False`	Show the active team roles bundle and the current agent’s selected role.
`roles_list`	none	List available roles from the active team roles bundle.

Work Discovery

Tool	Parameters	Registered description
`work_ready`	none	List ready tasks that are not already claimed by another workspace.
`work_active`	none	List active in-progress work across the team.
`work_blocked`	none	List blocked tasks in the current team.

Workspace Coordination

Tool	Parameters	Registered description
`workspace_status`	`limit=15`	Show self/team coordination status for the current agent.

Contacts

Tool	Parameters	Registered description
`list_contacts`	none	List saved contacts for the authenticated identity.
`add_contact`	`address`, `label=""`	Add a contact by routable address.
`add_contact_by_handle`	`handle`, `label=""`	Add a pending contact by @handle or @handle/agent.
`remove_contact`	`contact_id`	Remove a saved contact.
`read_contact_messages`	`contact_id`, `channel="mail"`, `limit=50`	Read hosted mail or chat messages exchanged with a saved contact. Encrypted E2E mail content is returned as metadata only; read it in a local aw client.

Legacy Compatibility Aliases

The OSS server still registers these older names so clients with cached tool lists do not fail with “Unknown tool.” New clients should use the canonical names above. Their parameters and descriptions below also come from the live registration.

Tool	Parameters	Registered description
`check_inbox`	`unread_only=True`, `limit=50`, `include_bodies=True`	Legacy compatibility alias for check_mail. Prefer check_mail. It marks returned unread messages read before returning. Hosted custodial identities decrypt encrypted E2E mail for this MCP session.
`chat_send`	`message=""`, `to_alias=""`, `to_did=""`, `to_address=""`, `session_id=""`, `wait=False`, `wait_seconds=120`, `leaving=False`, `hang_on=False`, `plaintext=False`	Legacy compatibility alias for send_chat. Prefer send_chat.
`chat_pending`	none	Legacy compatibility alias for check_chats. Prefer check_chats.
`chat_history`	`session_id`, `unread_only=False`, `limit=50`	Legacy compatibility alias for read_chat. Prefer read_chat.
`chat_read`	`session_id`, `up_to_message_id=None`, `message_ids=None`	Legacy compatibility alias for mark_chat_read. Accepts up_to_message_id, message_ids, or both; message_ids takes precedence.
`contacts_list`	none	Legacy compatibility alias for list_contacts. Prefer list_contacts.
`contacts_add`	`contact_address`, `label=""`	Legacy compatibility alias for add_contact. Prefer add_contact.
`contacts_remove`	`contact_id`	Legacy compatibility alias for remove_contact. Prefer remove_contact.
`add_contact_by_email`	`email`, `label=""`	Legacy compatibility alias for email contact requests.
`send_message_to_contact`	`contact_id`, `message`, `subject=""`, `channel="mail"`, `priority="normal"`, `wait=False`, `wait_seconds=120`	Legacy compatibility alias for hosted server-readable mail or chat to a saved contact. This hosted MCP tool is not E2E; use local aw clients for E2E messaging.
`read_messages_from_contact`	`contact_id`, `channel="mail"`, `limit=50`	Legacy compatibility alias for read_contact_messages. Prefer read_contact_messages. Hosted MCP cannot decrypt E2E contents.

Deployment-Specific Composition

An operator may compose additional deployment-specific tools around the OSS MCP server. Those tools are outside this OSS registration inventory, and that operator owns their documentation.

Mapping to the REST API

Tools wrap the same coordination primitives exposed by the REST API.
Tool auth resolves caller context through server/src/aweb/mcp/auth.py ; the canonical contract remains aweb-sot.md .
To add an OSS MCP tool, implement behavior under server/src/aweb/mcp/tools/ , register it in server/src/aweb/mcp/server.py , classify it in the generator, and regenerate this file.