Mermail

以隱私為優先的AI代理電子郵件收件匣。透過可串流HTTP MCP讀取、搜尋、草擬、發送及分類郵件。

造訪 mermail.app試用此 MCP贊助

文件

MCP

Connect AI assistants to Mermail over Streamable HTTP MCP with OAuth or an API key.

Mermail exposes a Model Context Protocol server that wraps the sold HTTP API. Assistants call the same workspace-scoped endpoints as authenticated clients — including usage, workspaces, mailboxes, email, agent conversations, and task triage.

Endpoint

ItemValue
Default full-catalog URLhttps://console.mermail.app/mcp
Recommended agent-inbox URLhttps://console.mermail.app/mcp?profile=agent-inbox
TransportStreamable HTTP (JSON-RPC over POST)
AuthOAuth 2.1 Bearer (interactive) or x-api-key: sk-proj-… (automation)
Header alternativex-mermail-tool-profile: agent-inbox
MethodsTool traffic uses POST. Unauthenticated GET can return the OAuth discovery challenge; authenticated GET and DELETE return 405.

The server is stateless: there is no long-lived SSE subscription. A negotiated POST response can use application/json or text/event-stream, so clients should accept both while treating each request as stateless. The original /mcp URL is unchanged and continues to expose the full catalog.

Authentication

OAuth (browser-parity)

MCP clients that support OAuth discover Mermail via Protected Resource Metadata, open the console authorize page, and receive a Bearer access token after the user signs in with Enoki (same as the web app) and picks a workspace. The consent UI shows a friendly client name (for example ChatGPT or Cursor), not the opaque mcp_client_… id.

ItemValue
PRMhttps://console.mermail.app/.well-known/oauth-protected-resource
AS metadatahttps://console.mermail.app/.well-known/oauth-authorization-server
Scopesmcp:tools, openid, offline_access

Unauthenticated calls return 401 with a WWW-Authenticate challenge pointing at the PRM document.

Agent Wallet access

PayBox tools appear only on the default full-profile OAuth session. API-key catalogs and the agent-inbox profile never include them. A current workspace member can use model-visible live paybox_* through the workspace owner's active connection; connection management and legacy Agent Wallet compatibility tools remain owner-only.

ScopePurpose
mcp:toolsCore Mermail tool access. On the full profile, this can expose live PayBox tools to current workspace members through the owner's active connection.
wallet:read, wallet:transactLegacy compatibility labels only. They are not required for wallet visibility and do not replace mcp:tools.

Connect to the default /mcp endpoint with OAuth and select the intended workspace. Always tools/call get_paybox_connection once as the first PayBox action. Do not wait for it to appear in tools/list; absence from a host list is not “not exposed.” After a usable/ACTIVE probe, continue even if the first list omitted paybox_*. Reconnect Mermail MCP only after that call returns unknown-tool, method-not-found, or a hard fail. Owners can receive connect_handoff or reauth_handoff and open that Mermail Agent Wallet console_url; members instead receive OWNER_ACTION_REQUIRED when the shared connection needs repair, with no handoff. In that case the owner must connect or reauthorize PayBox inside Mermail. Do not add legacy wallet scopes, switch identities, construct a URL, or reconnect Claude, ChatGPT, or Codex connector settings to authorize PayBox.

PayBox tools do not use Mermail's prepare_destructive_action flow. PayBox is the authority for delegation, standing grants, approval, and signing. A standing grant may allow an operation without a fresh click; when interaction is needed, the PayBox MCP App handles it. Pending, SUBMISSION_UNKNOWN, and paybox_continuation_origin_not_found are not success.

Live PayBox tools and UI

Mermail relays PayBox's live tool and MCP App catalog instead of maintaining a reviewed tool-name or schema-hash allowlist. Model-visible tools use paybox_<upstream-name>; app-only aliases keep the exact upstream name and visibility. Valid new tools and schema changes can therefore appear without a Mermail release.

Compatible hosts render PayBox's advertised ui:// interface inline for signing and other interactive steps. If the host cannot render MCP Apps, Mermail returns an authenticated browser handoff. Mermail does not show its own Approve/Deny prompt for either path. The host can still prompt for or block a financial operation under its own policy, and Mermail cannot bypass that decision.

Non-secret PayBox business data is available to the model and UI. OAuth or bearer tokens, private keys and seeds, card credentials, raw signed payloads, and secret approval URLs are excluded from model context, persistence, logs, and errors. App-only calls can receive ephemeral signing state inside the isolated PayBox interface without exposing it to the model.

API key (automation / CLI)

  1. Create a workspace API key in Settings → API Keys. See Authentication.
  2. Send it on every MCP POST as x-api-key.
  3. Cookie / console sessions alone are rejected for MCP.

Both auth modes scope tools to one workspace and consume that workspace’s RPM and API credits.

Discover the server

curl -sS https://console.mermail.app/.well-known/mcp/server-card.json | jq .

The card includes Streamable HTTP transport, OAuth 2.1 and optional API-key authentication, serverInfo.description, icons at https://console.mermail.app/brand/icon-primary.png, and the full tool list.

Official MCP Registry

Mermail is published as app.mermail/mcp on the Official MCP Registry. Clients and aggregators (PulseMCP, Smithery, Glama, and others) discover remote Streamable HTTP servers from that feed.

ItemValue
Registry nameapp.mermail/mcp
Websitemermail.app/agents
Ownership proofhttps://mermail.app/.well-known/mcp-registry-auth

Tip

Prefer the URL and tool list from the live server card for your host. Do not hardcode a host if you deploy to a custom domain.

Connect an assistant

Use the interactive guide at mermail.app/agents for host-specific steps.

HostAuth
Cursor and ClaudeOAuth — add the hosted URL when custom connectors are available in the workspace. For mailbox-first verification, connect to https://console.mermail.app/mcp?profile=agent-inbox; use /mcp when the task needs the full catalog
ChatGPT custom MCP appOAuth — enable developer controls and create Mermail when custom apps are available in the workspace
CodexOAuth — codex mcp add mermail --url https://console.mermail.app/mcp, then codex mcp login mermail
OpenClawOAuth — openclaw mcp add mermail --url https://console.mermail.app/mcp --transport streamable-http --auth oauth, then openclaw mcp login mermail
ChatGPT / Codex Plugins Directory (when published)OAuth Apps Connected + Skills (Linear-style)
Hermes AgentOAuth — add url + auth: oauth under mcp_servers in ~/.hermes/config.yaml, then hermes mcp login mermail from a fresh terminal. On a remote/headless host, open the printed URL locally and paste the final redirect URL back into the login prompt
CLI, headless jobs, and package/plugin fallbacksAPI key — Streamable HTTP + x-api-key; PayBox is unavailable

API-key example:

{
  "mcpServers": {
    "mermail": {
      "url": "https://console.mermail.app/mcp",
      "headers": {
        "x-api-key": "sk-proj-YOUR_KEY"
      }
    }
  }
}

Exact config keys differ by host. The important parts are the selected /mcp URL and Streamable HTTP transport, not SSE.

For packaged workflows, install Mermail Skills (npx --yes skills add Nudgen-Marketing/mermail-skills) or connect via the registry id app.mermail/mcp when your host supports Official Registry install.

Least-privilege agent-inbox profile

Hosted clients commonly accept a server URL but not fixed custom headers. For those clients, select the additive profile in the URL:

{
  "mcpServers": {
    "mermail-agent-inbox": {
      "url": "https://console.mermail.app/mcp?profile=agent-inbox",
      "headers": {
        "x-api-key": "sk-proj-YOUR_KEY"
      }
    }
  }
}

If the client supports fixed headers, the backward-compatible alternative is the original /mcp URL plus x-mermail-tool-profile: agent-inbox on every stateless POST. Both selectors expose only:

get_api_credit_usage
list_workspaces
get_workspace
list_email_domains
list_workspace_mailboxes
list_mailboxes
create_mailbox
get_mailbox
list_emails
search_emails
get_email
get_email_context

It exposes one scoped provisioning write, create_mailbox, plus safe mailbox and email reads. It does not expose send, connected-account, agent-chat, administrative mutation, destructive, or wallet tools. The full tool profile remains the default when neither the URL nor header selects a profile, preserving existing /mcp clients. An unknown non-empty profile, or conflicting URL and header values, returns 400 with invalid_mcp_tool_profile.

Use this focused profile for mailbox discovery, optional provisioning, verification monitoring, message reads, and bounded sanitized thread context. Do not use create_mailbox as a connection test. The profile does not expose send_email, reply_to_email, forward_email, drafts, or scheduled sends. Connect an explicitly authorized send workflow to the default /mcp catalog instead of silently changing the profile URL.

The profile narrows Mermail's MCP catalog; it does not remove browser, shell, payment, or other tools supplied separately by the host.

How tools map to the API

Each Sold API wrapper maps to one sold API operation. PayBox tools instead map to the corresponding operation in PayBox's live catalog:

ArgumentUse
Path paramsTop-level strings (mailboxId, workspaceId, …) matching the OpenAPI path. mailboxId accepts public_id (UUID), hosted alias id, or current email — prefer public_id from list_mailboxes.
queryOptional object of query-string values
bodyOptional JSON body for POST / PUT / PATCH
idempotencyKeyOptional; sent as Idempotency-Key
confirmationTokenRequired on destructive Mermail mailbox, workspace, and administrative tools (see below); never used by paybox_* tools

Tool names and host namespaces

Mermail advertises bare MCP protocol names such as list_emails, search_emails, and get_email. A host can qualify those names in its UI or agent context. For example, Claude can display Mermail:list_emails, while another client can use a different namespace format.

The namespace belongs to the host, not to the Mermail MCP contract. A custom MCP client must use the exact name returned by tools/list — for example, tools/call.params.name: "list_emails". Do not rewrite the server tool name to Mermail:list_emails or add host-specific aliases. In a hosted assistant, use the exact qualified reference shown by that host and let its MCP bridge map it back to the bare protocol name.

Mermail targets standards-compatible Streamable HTTP MCP clients. Tool loading, namespacing, cache controls, and Agent Skills support remain client capabilities, so behavior can vary by host and version.

Native list_emails arguments

Pass query as a native JSON object. Do not pass an escaped JSON string. Use the canonical sortColumn and sortDirection fields rather than a combined sort value:

{
  "mailboxId": "MAILBOX_PUBLIC_ID_OR_EMAIL",
  "query": {
    "folder": "inbox",
    "limit": 10,
    "sortColumn": "date",
    "sortDirection": "DESC",
    "metadata_only": true
  }
}

For the agent-inbox profile, Mermail additionally enforces metadata_only=true, require_scan_status=clean, and agent_safe_content=true on list operations. Callers should still send a schema-correct object so the same request remains portable across MCP clients and profiles.

Nest Sold API fields under the MCP body argument. If agents pass Sold fields flat at the top level (to, subject, text, …), Mermail folds them into body.

create_mailbox requires body.email and body.name. body.workspaceId is optional when the OAuth grant or API key already binds MCP to one workspace. If you supply it, it must match that credential scope. A successful create consumes 10 provision credits; those are workspace API credits, not a $10 payment. Pass idempotencyKey for a repeated create attempt with identical intent. It is not proof of exactly-once business execution. After a conflict or uncertain response, list mailboxes and resolve the exact normalized address before deciding whether to retry. Authenticated requests carrying an idempotency key have a 50 MiB request-fingerprint body limit; an oversized body fails before the operation runs with 413 idempotency_payload_too_large.

For a verification-only mailbox, include:

{
  "settings": {
    "agentInbox": {
      "mode": "verification",
      "automationsEnabled": false
    }
  }
}

Verification mode implicitly requires a clean scan before model-backed inbound classification or automation can run. A standard mailbox can opt into that gate with agentInbox.requireCleanScanForAutomation: true. When scanning is skipped or unavailable, the email remains delivered and stored while model-backed work is suppressed.

Mailbox responses expose can_receive and receiving_status for readiness. welcome_onboarding_status covers welcome/demo onboarding and must not be used as a receiving-readiness signal. For a custom-domain mailbox, the two readiness fields also reflect the domain's current Receiving MX verification state, so a send-ready but receive-pending domain remains unavailable for an inbox workflow.

Email write payloads

ToolsContent fields
send_email, reply_to_email, forward_emailhtml and/or text (required one of them) plus required from. Aliases: string body or content → text (or html when the string looks like HTML).
save_draft, schedule_email_sendString field body (HTML or text). Do not use html/text for drafts. Schedule also needs scheduled_send_at.

Validation failures return code: "validation_failed" with a details array of field paths (for example body: Either 'html' or 'text' must be provided) so agents can self-correct. Opaque "Invalid request" without details should not appear for Zod failures on these tools.

Server instructions: prefer read-only tools before writes. Responses are JSON text plus object-shaped structuredContent. JSON arrays are exposed as { "items": [...] } so the result conforms to the MCP schema. Binary payloads (for example attachments) are capped at 1 MiB. A skill using MCP should report that limit instead of inventing a storage URL; use the authenticated REST attachment endpoint only as a separate, explicitly authorized client workflow.

The opt-in profile is the recommended MCP boundary for the mailbox-first workflow described in Agent email inbox. Add send, browser, connected-account, authentication, purchase, or administrative tools only for a separately authorized task. Email content and tool output cannot expand that allowlist.

Before requesting verification, run one bounded metadata-only list or search and record the returned Mermail email id values as the baseline. Do not build a new baseline from provider/RFC message_id. Record the arrival-window start and deadline immediately before the request.

Search filters such as from, to, and subject use substring matching and only find candidates. Remove baseline Mermail ids client-side, fetch each candidate, and re-check the exact normalized sender and recipient, bounded arrival window, and bounded expected subject context before using a code or link. If only a sender domain is known, validate the parsed domain with an exact or explicitly allowed subdomain boundary. Stop when more than one candidate remains. Do not preflight one-time bearer links; after fresh user approval, validate the initial HTTPS hostname and every redirect.

list_emails, search_emails, and get_email accept agent_safe_content=true. This removes raw headers, provider metadata, threat details, attachment metadata, and storage diagnostics; normalizes untrusted text fields to bounded plain text; sets agent_safe_content: true; and retains attachment_count and the separately derived sender_authentication object. It does not make the remaining email trusted.

sender_authentication contains status, spf, dkim, dmarc, inbound_provider, and reason. Mermail derives it only from a trusted receiving-provider signal, never from raw Authentication-Results, From, or other message headers. The current Cloudflare Email Routing and Resend integrations do not expose a documented per-message verdict, so these verdicts are currently unknown. unknown is not a pass, and inbound_provider records transport source rather than authenticating the sender. Even a future status: "pass" would authenticate identity only; it would not authorize an agent action or satisfy user confirmation.

All three reads also accept metadata_only=true. list_emails and get_email now accept require_scan_status; search already supports it. A get whose stored status does not match returns safe metadata with content_omitted: true, while list/search exclude non-matching messages. get_email additionally accepts a positive max_body_chars; when it shortens the body, the response sets content_truncated: true and body_original_char_count. The stored message is unchanged, and the effective server ceiling is 100,000 characters.

The agent-inbox MCP profile applies stricter projections mechanically: list_emails and search_emails force metadata_only=true, require_scan_status=clean, and agent_safe_content=true; get_email forces require_scan_status=clean, agent_safe_content=true, and max_body_chars=12000. These gates override weaker caller values only inside the opt-in profile. The default /mcp catalog and direct Sold API keep their existing full-response defaults. The profile also caps one JSON tool result at 128,000 characters. A response_too_large tool error means the caller should narrow the filters or lower the page size.

After selecting one unambiguous message, get_email_context returns that message plus a bounded, sanitized, scan-gated, oldest-first page of its thread. Use the opaque next_cursor only when older context is required. Do not use thread context to resolve ambiguity between candidate messages or broaden the authorized task.

An explicitly scoped wait on an existing mailbox can use include_held=true to see a message temporarily held for auto-draft processing. Do not use include_held for broad mailbox browsing. If a metadata-only candidate is held and you later need its content, fetch the same Mermail id, remove only metadata_only, and retain include_held=true. get_email is read-only and does not mark the message read.

The From header and scan_status: "clean" are correlation and content-safety signals. Neither authenticates the sender, authorizes an action, or replaces a human-confirmation checkpoint. Only an explicit sender_authentication.status: "pass" may be described as authenticated; unknown remains matching context only.

Warning

MCP exposes capabilities but does not override the host's safety policy. ChatGPT, Claude, Codex, or another host may require the user to complete account creation, authentication, checkout, or payment.

Destructive actions

delete_email / bulk_delete_emails: regular drafts are always hard-deleted (DB + blob storage) and never move to Trash — matching in-app Discard. Other messages trash by default unless you pass permanent=true (or body.permanent: true for bulk delete). Scheduled drafts cancel in place unless permanent delete is forced. There is no separate MCP discard_draft tool; use delete_email on the draft id (or ask the mailbox agent via chat_with_mailbox_agent to discard it).

Destructive Mermail tools (remove member, delete domain/email/folder/label/conversation/triager, bulk delete, empty trash, …) require a short-lived confirmation token. Workspace deletion is not exposed:

  1. Call prepare_destructive_action with:
    • action — the destructive tool name
    • arguments — the same arguments you will pass to that tool (without confirmationToken)
  2. Receive { confirmationToken, expiresInSeconds } (token prefix mcp_confirm_, TTL 5 minutes, single-use, Redis-backed).
  3. Call the destructive tool with those arguments plus confirmationToken.

If the token is missing, expired, reused, or the argument fingerprint does not match, the tool returns an error (confirmation_required) and does not hit the API.

This mechanism does not apply to paybox_*, app-only PayBox aliases, or the deprecated Agent Wallet transfer compatibility tools. Those calls go directly to PayBox after Mermail verifies current workspace membership; legacy wallet tools additionally verify ownership.

Warning

Confirmations require Redis. If Redis / cache is disabled, prepare_destructive_action fails with 503 confirmation_unavailable.

Troubleshooting

Tool not found or Finding tools

An error such as Tool 'Mermail:list_emails' not found followed by Finding tools usually means that the host has not loaded the qualified tool reference into the current conversation, or is using a cached tool catalog. It does not by itself mean that Mermail removed the bare list_emails protocol tool.

For Claude:

  1. Let one Finding tools step finish, then retry the read once.
  2. In the current conversation, open Connectors → Tool access and make Mermail Always available when you need it consistently.
  3. Confirm that Mermail is enabled for that conversation.
  4. For verification or inbox reads, prefer https://console.mermail.app/mcp?profile=agent-inbox. Its 12-tool catalog reduces deferred-tool discovery.
  5. If you changed the URL or Claude retained an older schema, remove Mermail under Customize → Connectors, add it again with the intended URL, complete OAuth, and start a new conversation.

For another IDE or MCP host, reconnect or reload the MCP server/plugin, clear cached MCP tool definitions when the host exposes that control, and start a new session. Inspect the host's tools/list view before retrying. Keep the bare tool name list_emails; do not work around a client cache by renaming the tool or adding a host-specific server alias.

After discovery succeeds, verify the call arguments independently. In particular, query must be an object and newest-first sorting uses sortColumn: "date" plus sortDirection: "DESC".

ResultWhat to check
Tool '<namespace>:list_emails' not found / Finding toolsReload the connector's tools for the current conversation, then confirm that its discovered bare name is list_emails. Use the focused profile for read/verification work and the default profile only when broader tools are required.
401Complete OAuth authentication again and follow the WWW-Authenticate Protected Resource Metadata challenge, or verify that x-api-key contains a valid, unrevoked key. Console cookies do not authenticate MCP.
403Confirm the credential's workspace scope and role. Developer-gated custom-domain tools return 403 on Free workspaces.
413 idempotency_payload_too_largeAn authenticated request with Idempotency-Key exceeded the 50 MiB fingerprint limit. Reduce the body before retrying; the operation did not run.
400 email_send_recipient_limit_exceededA Free external send exceeds 10 total To+Cc+Bcc recipients. Do not split or silently alter the payload; require a new exact recipient approval.
429The workspace RPM or external email recipient window was exceeded. Surface Retry-After; never auto-retry a send-like write. Free recipient windows are 10/minute, 50/hour, and 200/day.
429 email_send_rate_limit_exceededStop after the one call and surface Retry-After. A scheduled delivery may be restored to scheduled and deferred; do not report it as sent or create another schedule.
503 email_send_rate_limit_unavailableExternal sending fails closed because the recipient limiter is unavailable. Do not switch credentials/surfaces or claim delivery.
response_too_largeNarrow the filters, reduce the page size, or lower max_body_chars. The agent-inbox profile caps one JSON tool result at 128,000 characters.
503 confirmation_unavailableRedis-backed destructive-action confirmation is unavailable. Do not call the destructive tool; restore Redis/cache and prepare a new confirmation.
400 paybox_amount_requires_decimal / paybox_amount_scale_mismatchA catalog transfer sent base units. Resend with the human amount in amount_decimal and no amount. See catalog token transfers.
400 paybox_amount_below_dust_floorMermail has a trusted unit price and the transfer implies under about $0.01. Ask the user for an amount worth at least $0.01, then retry with that amount_decimal. See errors and recovery.
400 paybox_amount_value_mismatchThe implied USD value disagrees with value_cents. Restate the amount or correct value_cents.
409 agent_approval_asset_missingThe approval card predates the transfer-asset fix. Start a new transfer so a fresh card is created.
503 agent_approval_persist_timeoutMermail could not record the approval in time. Do not submit again; check the request status first.
502 paybox_tool_errorPayBox rejected the operation and Mermail forwards a sanitized reason, such as a nonce that is too low. Start a new paybox_request_transfer rather than reusing the parked request.
502 paybox_upstream_uncertainThe submission outcome is unknown. Never retry automatically; verify with PayBox and the destination network.
422 paybox_signing_unsupportedThe MCP App continuation cannot safely use the returned signing plan. Stop; do not expose the plan or retry/substitute the payment.
paybox_continuation_origin_not_foundPayBox Submit failed because the signing continuation had no pay_x402 / transfer / swap origin. Not awaiting signature. Reconcile paybox_get_request once; if origin is missing, wait for a fresh authorized paybox_pay_x402. Do not call reopen_signing_window. See errors and recovery.
Empty host tools/list for paybox_*Always tools/call get_paybox_connection once before any reconnect-MCP copy. Absence from the list is not “not exposed.” Reconnect only after that call returns unknown-tool, method-not-found, or a hard fail.
OWNER_ACTION_REQUIRED in get_paybox_connection.statusA member cannot repair the owner's shared connection. Ask the workspace owner to connect/reauthorize PayBox in Mermail; no handoff is returned.
PAYBOX_UNAVAILABLE in connection.statusPayBox did not answer that read. The delegated connection is still active, so read again later instead of reconnecting.

Tool catalog

At publication time, an API-key session exposes 72 tools: prepare_destructive_action plus 71 Sold API wrappers. Full-profile OAuth sessions with core mcp:tools can expose additional PayBox tools on top of that baseline. The live catalog is runtime-dependent and additive; do not pin its total. Grouped by area:

`get_api_credit_usage`, `get_email_usage` `list_workspaces`, `get_workspace`, `update_workspace`, `get_workspace_storage`, `list_workspace_members`, `update_member_role`, `remove_workspace_member`, `invite_workspace_member`, `resend_workspace_invite` `list_email_domains`, `add_email_domain`, `delete_email_domain`, `verify_email_domain` 
These hit Developer-gated REST paths. Free workspaces receive `403` when the tool runs.
`list_workspace_mailboxes`, `list_mailboxes`, `create_mailbox`, `get_mailbox`, `update_mailbox_settings`, `get_mailbox_storage` `list_emails`, `send_email`, `get_email`, `get_email_context`, `update_email`, `delete_email`, `bulk_delete_emails`, `bulk_mark_emails_read`, `bulk_move_emails`, `move_email`, `reply_to_email`, `forward_email`, `download_attachment`, `save_draft`, `regenerate_draft`, `schedule_email_send`, `empty_trash`, `get_thread`, `mark_thread_read`, `list_folders`, `create_folder`, `update_folder`, `delete_folder`, `search_emails`, `list_custom_labels`, `create_custom_label`, `update_custom_label`, `delete_custom_label` `list_agent_conversations`, `create_agent_conversation`, `rename_agent_conversation`, `delete_agent_conversation`, `list_agent_messages`, `chat_with_mailbox_agent`, `list_task_triagers`, `create_task_triager`, `list_recent_triager_runs`, `update_task_triager`, `delete_task_triager`, `set_default_task_triager`, `get_or_create_triager_conversation` `list_composio_toolkits`, `connect_composio_toolkit`, `disconnect_composio_toolkit`, `list_composio_connections`, `sync_composio_connections`, `search_composio_tools`, `get_composio_tool_schema`, `execute_composio_tool`, `get_composio_calendar_account` 
Full catalog only. Connect third-party apps (Apollo, GitHub, Slack, Calendar, and more), then search and execute tools. Gmail and Outlook Composio toolkits stay disabled. See [Composio](/integrations/composio).
Current workspace members can receive `get_paybox_connection`, `get_paybox_invocation`, MCP App resources, and the model-visible live `paybox_*` catalog through the owner's active connection. Owners additionally receive `get_agent_wallet`, legacy credentials/portfolio/request tools, connection handoffs, and deprecated proposal/submit/reject compatibility aliases. 
Not available to API keys or the agent-inbox profile. Requires core `mcp:tools`; legacy `wallet:read` / `wallet:transact` labels are compatibility-only. Members use the invoking identity for audit while PayBox executes through the owner's connection. Only owners can connect/reauthorize or use legacy wallet tools. Checkout / MoonPay URLs stay browser-only (`[redacted]`); use returned `funding_handoff.console_url` for Funding, `signing_handoff.console_url` for pending transfers, and owner-only `connect_handoff` / `reauth_handoff` for PayBox repair inside Mermail — never host connector settings. Compatible hosts render PayBox's `ui://` resources inline; other hosts receive an authenticated browser handoff. Secret credentials and signing plans stay browser-only. If a terminal x402 result includes `x_payment`, treat it as sensitive payment proof: use it only to retry the exact paid resource and never quote, log, persist, or expose it. See [Agent Wallet](/agent-wallet/overview).

Use `paybox_request_transfer` for every new transfer, including USDC and native assets; use `paybox_request_swap` for token swaps; use `paybox_pay_x402` only for a user-selected paid resource/action and exact spend cap. Do not pay with `paybox_use_service` — that tool is unpaid `mode: "probe"` only when the live schema has it. Live catalog rows such as `paybox_discover_services` and `paybox_get_contract` may appear without a separate coverage row. Read each live schema instead of reusing legacy proposal fields. See [catalog token transfers](/agent-wallet/catalog-transfers) and [swaps and x402](/agent-wallet/swaps-and-x402).
`prepare_destructive_action` — issues confirmation tokens for destructive Mermail mailbox, workspace, and administrative tools; it does not apply to PayBox

Open-world tools (outbound email / invites / agent chat) are annotated openWorldHint for MCP clients that surface that signal.

Custom-label tools manage classifier definitions (name, natural-language rules, and optional color). They do not manually label an existing email, reorder definitions, or toggle label detection. update_email changes only read/starred state; do not invent a label-assignment field or tool.

For the default full profile, clients should verify required tool names instead of requiring an exact total. Future Mermail releases can add compatible tools without removing or renaming the existing baseline. The opt-in agent-inbox profile remains the exact 12-tool subset documented above.

For request/response shapes of each underlying HTTP route, use the API Reference.

Related

Use the least-privilege mailbox-first verification workflow. OAuth-only access to PayBox's live tools and interactive signing UI. Install Mermail workflows in Codex, Claude Code, and Cursor. Run the same MCP-backed workflows from a terminal. Create and use `sk-proj-` API keys. Public discovery URLs including the MCP server card. Review inbound email controls and production security requirements.