Mermail
About
Privacy-first email inboxes for AI agents. Read, search, draft, send, and triage mail over Streamable HTTP MCP.
Details
- Author
- Unknown
- Categories
- Communication, Knowledge Base, Other, Search
Jump to
Connect AI assistants to Mermail over Streamable HTTP MCP with OAuth or an API key.
The server isstateless: there is no long-lived SSE subscription. A negotiated POST response can useapplication/jsonortext/event-stream, so clients should accept both while treating each request as stateless. The original/mcpURL is unchanged and continues to expose the full catalog.
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 opaquemcp_client_…id.
Unauthenticated calls return401with aWWW-Authenticatechallenge pointing at the PRM document.
PayBox tools appear only on the default full-profileOAuthsession. API-key catalogs and theagent-inboxprofile never include them. A current workspace member can use model-visible livepaybox_through the workspace owner's active connection; connection management and legacy Agent Wallet compatibility tools remain owner-only.
Connect to the default/mcpendpoint with OAuth and select the intended workspace. Alwaystools/callget_paybox_connectiononce as the first PayBox action. Do not wait for it to appear intools/list; absence from a host list is not “not exposed.” After a usable/ACTIVEprobe, continue even if the first list omittedpaybox_. Reconnect Mermail MCP only after that call returns unknown-tool, method-not-found, or a hard fail. Owners can receiveconnect_handofforreauth_handoffand open that Mermail Agent Walletconsole_url; members instead receiveOWNER_ACTION_REQUIREDwhen 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'sprepare_destructive_actionflow. 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, andpaybox_continuation_origin_not_foundare not success.
Mermail relays PayBox's live tool and MCP App catalog instead of maintaining a reviewed tool-name or schema-hash allowlist. Model-visible tools usepaybox_<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 advertisedui://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.
Both auth modes scope tools to one workspace and consume that workspace’sRPMandAPI credits.
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-keyauthentication,serverInfo.description, icons athttps://console.mermail.app/brand/icon-primary.png, and the full tool list.
Mermail is published asapp.mermail/mcpon theOfficial MCP Registry. Clients and aggregators (PulseMCP, Smithery, Glama, and others) discover remote Streamable HTTP servers from that feed.
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.
Use the interactive guide atmermail.app/agentsfor host-specific steps.
{ "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/mcpURL and Streamable HTTP transport, not SSE.
For packaged workflows, installMermail Skills(npx skills add Nudgen-Marketing/mermail-skills) or connect via the registry idapp.mermail/mcpwhen your host supports Official Registry install.
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/mcpURL plusx-mermail-tool-profile: agent-inboxon every statelessPOST. 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/mcpclients. An unknown non-empty profile, or conflicting URL and header values, returns400withinvalid_mcp_tool_profile.
Use this focused profile for mailbox discovery, optional provisioning, verification monitoring, message reads, and bounded sanitized thread context. Do not usecreate_mailboxas a connection test. The profile doesnotexposesend_email,reply_to_email,forward_email, drafts, or scheduled sends. Connect an explicitly authorized send workflow to the default/mcpcatalog 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.
Each Sold API wrapper maps to one sold API operation. PayBox tools instead map to the corresponding operation in PayBox's live catalog:
Mermail advertises bare MCP protocol names such aslist_emails,search_emails, andget_email. A host can qualify those names in its UI or agent context. For example, Claude can displayMermail: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 bytools/list— for example,tools/call.params.name: "list_emails". Do not rewrite the server tool name toMermail:list_emailsor 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.
Passqueryas a native JSON object. Do not pass an escaped JSON string. Use the canonicalsortColumnandsortDirectionfields rather than a combinedsortvalue:
{ "mailboxId": "MAILBOX_PUBLIC_ID_OR_EMAIL", "query": { "folder": "inbox", "limit": 10, "sortColumn": "date", "sortDirection": "DESC", "metadata_only": true } }
For theagent-inboxprofile, Mermail additionally enforcesmetadata_only=true,require_scan_status=clean, andagent_safe_content=trueon 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 MCPbodyargument. If agents pass Sold fields flat at the top level (to,subject,text, …), Mermail folds them intobody.
create_mailboxrequiresbody.emailandbody.name.body.workspaceIdis 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 consumes10 provision credits; those are workspace API credits, not a$10payment. PassidempotencyKeyfor 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 with413idempotency_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 withagentInbox.requireCleanScanForAutomation: true. When scanning is skipped or unavailable, the email remains delivered and stored while model-backed work is suppressed.
Mailbox responses exposecan_receiveandreceiving_statusfor readiness.welcome_onboarding_statuscovers 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.
Validation failures returncode: "validation_failed"with adetailsarray of field paths (for examplebody: 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-shapedstructuredContent. JSON arrays are exposed as{ "items": [...] }so the result conforms to the MCP schema. Binary payloads (for example attachments) are capped at1 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 inAgent 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 emailidvalues as the baseline. Do not build a new baseline from provider/RFCmessage_id. Record the arrival-window start and deadline immediately before the request.
Search filters such asfrom,to, andsubjectuse 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, andget_emailacceptagent_safe_content=true. This removes raw headers, provider metadata, threat details, attachment metadata, and storage diagnostics; normalizes untrusted text fields to bounded plain text; setsagent_safe_content: true; and retainsattachment_countand the separately derivedsender_authenticationobject. It does not make the remaining email trusted.
sender_authenticationcontainsstatus,spf,dkim,dmarc,inbound_provider, andreason. Mermail derives it only from a trusted receiving-provider signal, never from rawAuthentication-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 currentlyunknown.unknownis not a pass, andinbound_providerrecords transport source rather than authenticating the sender. Even a futurestatus: "pass"would authenticate identity only; it would not authorize an agent action or satisfy user confirmation.
All three reads also acceptmetadata_only=true.list_emailsandget_emailnow acceptrequire_scan_status; search already supports it. A get whose stored status does not match returns safe metadata withcontent_omitted: true, while list/search exclude non-matching messages.get_emailadditionally accepts a positivemax_body_chars; when it shortens the body, the response setscontent_truncated: trueandbody_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_emailsandsearch_emailsforcemetadata_only=true,require_scan_status=clean, andagent_safe_content=true;get_emailforcesrequire_scan_status=clean,agent_safe_content=true, andmax_body_chars=12000. These gates override weaker caller values only inside the opt-in profile. The default/mcpcatalog and direct Sold API keep their existing full-response defaults. The profile also caps one JSON tool result at 128,000 characters. Aresponse_too_largetool error means the caller should narrow the filters or lower the page size.
After selecting one unambiguous message,get_email_contextreturns that message plus a bounded, sanitized, scan-gated, oldest-first page of its thread. Use the opaquenext_cursoronly 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 useinclude_held=trueto see a message temporarily held for auto-draft processing. Do not useinclude_heldfor broad mailbox browsing. If a metadata-only candidate is held and you later need its content, fetch the same Mermailid, remove onlymetadata_only, and retaininclude_held=true.get_emailis read-only and does not mark the message read.
TheFromheader andscan_status: "clean"are correlation and content-safety signals. Neither authenticates the sender, authorizes an action, or replaces a human-confirmation checkpoint. Only an explicitsender_authentication.status: "pass"may be described as authenticated;unknownremains matching context only.
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.
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 passpermanent=true(orbody.permanent: truefor bulk delete). Scheduled drafts cancel in place unless permanent delete is forced. There is no separate MCPdiscard_drafttool; usedelete_emailon the draft id (or ask the mailbox agent viachat_with_mailbox_agentto 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:
- Callprepare_destructive_actionwith:
- action— the destructive tool name
- arguments— the same arguments you will pass to that tool (withoutconfirmationToken)
If the token is missing, expired, reused, or the argument fingerprint does not match, the tool returns an error (confirmation_required) and doesnothit the API.
This mechanism does not apply topaybox_*, 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.
Confirmations require Redis. If Redis / cache is disabled,prepare_destructive_actionfails with503confirmation_unavailable.
An error such asTool 'Mermail:list_emails' not foundfollowed byFinding toolsusually 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 barelist_emailsprotocol tool.
- Let oneFinding toolsstep finish, then retry the read once.
- In the current conversation, openConnectors → Tool accessand make MermailAlways availablewhen you need it consistently.
- Confirm that Mermail is enabled for that conversation.
- For verification or inbox reads, preferhttps://console.mermail.app/mcp?profile=agent-inbox. Its 12-tool catalog reduces deferred-tool discovery.
- If you changed the URL or Claude retained an older schema, remove Mermail underCustomize → 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'stools/listview before retrying. Keep the bare tool namelist_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,querymust be an object and newest-first sorting usessortColumn: "date"plussortDirection: "DESC".
At publication time, anAPI-keysession exposes72tools:prepare_destructive_actionplus71Sold API wrappers. Full-profileOAuthsessions with coremcp:toolscan 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:
These hit Developer-gated REST paths. Free workspaces receive 403 when the tool runs.
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.
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. 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 and swaps and x402.
Open-world tools (outbound email / invites / agent chat) are annotatedopenWorldHintfor MCP clients that surface that signal.
Custom-label tools manage classifier definitions (name, natural-languagerules, and optionalcolor). They do not manually label an existing email, reorder definitions, or toggle label detection.update_emailchanges 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-inagent-inboxprofile remains the exact 12-tool subset documented above.
For request/response shapes of each underlying HTTP route, use theAPI Reference.
Connect your Plaud recordings to any MCP-compatible AI client. Search recordings, read transcripts, and generate documents without leaving your AI assistant.
Fetch, convert, and search AWS documentation pages, with recommendations for related content.
Create and read feature flags, review experiments, generate flag types, search docs, and interact with GrowthBook's feature flagging and experimentation platform.
Quran-focused MCP server for ayah translation, tafsir, mutashabihat lookups, recitation playlists, and prayer times.
Provides AI assistants with intelligent access to ML textbook content for creating accurate, source-grounded documentation.
Search Apple's Developer Documentation with smart search and wildcard support.
Access, search, and get recommendations from public AWS documentation.
Caesar is a free, keyless web search API for AI agents. Its remote MCP server exposes web_search (ranked results with citable provenance) and web_fetch (full pages as clean markdown), and works anonymously with no API key.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
