API Reference

Maho Browser runs an MCP (Model Context Protocol) server inside the browser process. When Mail is enabled and you grant read access, that server exposes mail_* tools so an agent can read your mailbox.

There is no standalone Mail daemon and no separate MCP binary. The tools live in the browser, and they disappear from tool discovery when Mail is off.

Examples use placeholder IDs. Use real IDs from your own mailbox.

Connection

Point your MCP client at the stdio bridge that ships with the CLI:

maho mcp

The bridge forwards bytes to the browser’s local socket. Maho Browser must be running, and Mail must be enabled for the profile (Settings > Features > Mail). See Agent Protocol for transport and authentication detail.

Gates

Every mail_* read tool is checked in this order on both discovery and invocation:

1. Tool recognized. Unknown mail_* names are denied with mail_tool_unknown.
2. Feature enabled (maho.mail.enabled). Off by default on new profiles. Denied with mail_feature_disabled.
3. Helper ready. The profile-scoped Mail helper must have finished starting. A helper that is still starting is denied with mail_helper_starting. Draining, stopped, or failed helpers are denied with mail_helper_unavailable.
4. Global tool policy. A deny-all policy is denied with mail_global_policy_denied.
5. Read consent (maho.ai.mail_read_allowed, the Allow AI to read Mail setting). Off by default, and a global allow policy never substitutes for it. Denied with mail_read_consent_required.

Write and account-mutating tools stop at step 4 and then require a typed, per-call approval prompt (mail_typed_approval_required). Rejecting the prompt returns mail_typed_approval_denied.

Denials arrive as JSON-RPC error code -32008 with the reason code as the message. Mail arguments are redacted in denied requests, so a denial never leaks message content. Read consent is rechecked when the helper’s result comes back, so revoking it mid-flight cancels the in-flight read.

Available tools

Tool	Description
mail_list_accounts	List all email accounts
mail_list_folders	List folders for an account
mail_list_emails	List emails in a folder
mail_get_email	Get full email content
mail_search_emails	Full-text search across emails
mail_list_thread	List all emails in a thread

mail_extract_otp is also available under the same read gates. Write, draft, flag, and account tools follow the typed-approval path described above.