MCP and Agent access
Overview
Section titled “Overview”Mail tools are available through Maho Browser’s MCP and Agent surfaces. Maho Browser and its profile-scoped Mail helper must be running. There is no standalone Mail daemon, no separate Mail binary, and no Mail server that outlives the browser.
MCP clients connect through maho mcp, the stdio bridge shipped with the CLI.
It forwards bytes to the browser’s local socket; the protocol itself lives in
the browser process. See Agent Protocol.
Read tools require all of the following:
- Mail is enabled for the profile (
maho.mail.enabled, off by default). - The Mail helper has finished starting and is ready.
- The global tool policy is not set to deny.
- Allow AI to read Mail is enabled in Settings
(
maho.ai.mail_read_allowed, off by default).
A global allow policy never substitutes for Mail-read consent. Write and account-changing tools go through the normal typed tool-call approval instead.
Denial reasons
Section titled “Denial reasons”Discovery and invocation return stable reason codes. The gate rows are
evaluated in the order shown; completion-time and surface-specific rows apply
after dispatch. Over MCP they arrive as JSON-RPC error code -32008 with the
reason code as the message.
| Reason code | Meaning |
|---|---|
mail_tool_unknown | The tool name is not a recognized Mail tool. |
mail_feature_disabled | Mail is off for this profile. Enable it in Settings > Features > Mail. |
mail_helper_starting | The Mail helper is still starting. Retry once it is ready. |
mail_helper_unavailable | The Mail helper is draining, stopped, or failed. Retry once it is ready. |
mail_helper_generation_changed | The helper restarted while a read was in flight, so the result was discarded. |
mail_tool_not_available_on_agent | This Mail tool is not exposed on the current Agent surface. |
mail_global_policy_denied | The global tool policy is set to deny all. |
mail_read_consent_required | Allow AI to read Mail is off. Grant it in Settings. |
mail_typed_approval_required | A write or account tool needs the typed per-call approval prompt. |
mail_typed_approval_denied | The user rejected the typed approval prompt. |
credential_typing_approval_required | Generic browser_type requested credential-field typing and requires the per-call user approval gate. |
credential_typing_denied | The user rejected the credential-typing approval prompt. |
The credential-typing codes are shared public authorization contract
strings across Browser and Agent code. allow_credentials requests the gate;
it never counts as approval by itself. When the flag is absent, generic typing
into a credential-class field remains blocked. The in-browser Agent keeps its
existing approval plus Vault-sourced credential boundary: its already-recorded
action approval is not followed by a second native prompt, and generic
browser_type still cannot bypass Vault filling for credential fields.
Denied requests redact Mail arguments and return only the reason code, so a denial never returns message content. Mail tools are also hidden from tool discovery while the feature is disabled.
Read tools
Section titled “Read tools”Read access covers mail_list_accounts, mail_list_folders,
mail_list_emails, mail_get_email, mail_search_emails, mail_list_thread,
and mail_extract_otp. Per-tool parameters are in the
API Reference.
Write and account tools
Section titled “Write and account tools”Sending, drafting, flagging, moving, deleting, and account mutation are sensitive. Each request shows the typed approval surface before the Browser dispatches it to Mail, under every non-deny global policy.
Revoking Mail-read consent cancels pending reads. Consent is rechecked when the helper’s result comes back, so a late result cannot reach the Agent or MCP caller after you turn the permission off.