Security Model

Mailhub MCP combines user authentication, account policy, existing permissions, server-side confirmation, and spend controls. No single one of them is the answer — access requires all of them to allow the action.

Boundary	What Mailhub enforces	Canonical detail	Known limitation
Who the assistant is	User OAuth authorization with PKCE; the assistant inherits that user's permissions and holds no key of its own	Authentication	A public client holds no secret; PKCE carries that protection
Whether agents are allowed at all	Agent Access, an account-level gate that grants no permission of its own	Authentication	Turning it off is not immediate — see below
What that identity may do	The authorizing user's existing Mailhub permissions	Before You Connect	Rates need update access despite being read-shaped
Whether a change runs	confirm: true on the call, refused server-side without it	Confirmations & Spend Safety	It establishes the call carried the value, not how a client obtained approval
How much can be spent	Wallet balance and a rolling 24-hour agent spend limit, both checked before money moves	Confirmations & Spend Safety	Cancelling a Label is not an automatic refund
Change frequency	A guard of about 10 changing calls per minute per account	Confirmations & Spend Safety	Qualified, not an exact distributed quota
Whose data is reachable	Account checks on every identifier	Below	Parent-account scope only
What leaves in the conversation	Label files stay out; only a Mailhub link is returned	Below	The link is a link, not a credential

The sections below cover only what is unique to a security review. The operational rules behind each control live at the canonical pages named above.

The assistant acts as you## The assistant acts as you

Mailhub MCP does not give an assistant a separate super-user identity. The assistant acts as the Mailhub user who authorized the connection.

• Identity is your ordinary Mailhub user. There is no service account and no API key in this flow.
• Your existing roles and permissions continue to apply. MCP grants nothing beyond them; what you cannot do in the Mailhub application, the assistant cannot do for you.
• The account must also allow agents. A valid authorization is not enough on its own if Agent Access is off.
• A confirmed call is still subject to everything else. Confirming states intent; it does not bypass permissions or business rules.

See Authentication and Before You Connect.

OAuth and PKCE

Protocol	OAuth 2.1, Authorization Code
PKCE	Required
Client type	Public — no client secret
Scope	mcp.tools
Registration	By Mailhub, in advance

• PKCE binds the authorization code to the client that started the flow, so an intercepted code cannot be exchanged by anyone else. It is required precisely because the client is public and holds no secret.
• The absence of a client secret is deliberate, not an omission: a public client cannot keep one, so the protection comes from PKCE and the redirect allowlist instead.
• Sign-in is the normal Mailhub browser flow, including two-factor authentication when your user has it enabled, followed by an explicit consent step.
• Consent is not authorization. Approving tells Mailhub who the assistant acts as; Mailhub still applies every check below.
• Mailhub does not implement dynamic client registration. Only a client Mailhub registered in advance can connect, and being MCP-capable is not by itself enough.

Access is bound to the MCP resource

The MCP server is treated as an OAuth protected resource. A client discovers the authorization server and the required scope from the server's protected-resource metadata, and the authorization it then obtains is bound to that resource.

Authorization issued for Mailhub MCP is scoped to the MCP protected resource rather than being a general-purpose credential for unrelated Mailhub services.

Agent Access is a second gate

Agent Access is an account-level switch, off by default, that an authorized account user must turn on.

• It does not grant any role or permission, and it takes none away. It only allows or denies agent access for the account as a whole.
• A user can complete the OAuth consent successfully while every tool call stays blocked, because Agent Access is off.
• The assistant cannot enable Agent Access for itself, and it cannot raise its own spend limit. Those are actions for a person in Mailhub.

Access therefore requires both a valid user authorization and an account that allows agents.

What each operation requires

The assistant can do exactly what the authorizing user can do — Before You Connect carries the per-tool permission table. Two nuances matter for a review:

• Getting Rates is read-shaped but needs update access to Orders. A user restricted to view access can browse Orders and fetch Label links, and will be refused Rates.
• confirm: true is an intent gate, not a permission grant. It never widens what the user may do.

Account isolation

Every MCP request is evaluated in the context of the authenticated user's account.

An identifier is not a key

Knowing an Order, Shipment, or Label identifier is not sufficient to access it. Mailhub still applies the authenticated user's account and permission checks, and a resource outside that context is not returned as accessible data — it is answered the same way as something that does not exist, so its existence is not revealed.

Current scope boundary

Mailhub MCP currently operates at the parent-account level, and provides no sub-account selection or switching mechanism today. Authorization cannot be narrowed to a chosen sub-account through the current MCP surface. This is a scope boundary of what MCP exposes today — see Limits & Current Scope.

Changing actions require confirmation

Exactly four tools change state: mailhub_create_order, mailhub_update_order_status, mailhub_buy_label, and mailhub_cancel_label.

• Each requires an explicit confirm: true.
• Mailhub checks it, rather than trusting the assistant or its interface.
• Missing or false confirmation is refused, and nothing runs.
• The default for a changing action is to deny unless explicitly confirmed.
• A client invoking a tool directly cannot bypass the rule; it is applied on the server side of the connection.

The assistant can propose a change, but Mailhub still requires explicit confirmation before executing it. See Confirmations & Spend Safety.

Financial transaction safeguards

mailhub_buy_label is the current money-moving MCP action; no other tool spends anything.

• It spends real account wallet funds and requires explicit confirmation.
• The wallet balance must cover the purchase.
• A rolling 24-hour agent spend control applies to Label purchases made through MCP. The stored default limit is 1000 in the account wallet's own currency, and an account with no limit configured has no agent ceiling.
• Balance and spend allowance are independent checks — passing one says nothing about the other.
• The assistant cannot increase its own spend limit.
• Cancelling a Label does not automatically return funds to the wallet, and the original purchase still counts for the rest of its rolling window.

Write-rate guard

Mailhub currently targets a guard of about 10 changing MCP calls per minute per account.

• It is a request-rate safety guard, not a billing or spend quota.
• Read tools do not consume it.
• An unconfirmed change is refused before it counts as an accepted change.

Retry safety is tool-specific

Safety depends on the semantics of the specific tool, not on a universal retry guarantee.

• mailhub_create_order is not deduplicated: repeating a confirmed create can create a second Order.
• Repeating the same Label purchase will not buy a second Label — server-owned protection that covers Label purchase only and does not extend to the other changing tools.
• Repeating a status change that already applied is refused as already in that status.
• Repeating a cancellation for an already-cancelled Label is safe.

Do not assume every change is safe to repeat. See Errors & Troubleshooting.

Label files stay out of the conversation

mailhub_download_label returns a link into the Mailhub application, not the Label file. Opening and downloading the Label remains an action taken in Mailhub, by a signed-in person.

Format names are PDF, ZPL203DPI, ZPL300DPI, and ZPL600DPI; the tool reports which are available, not the files themselves. See Working with Labels.

Session lifetime and stopping access

Access token lifetime	60 minutes
Refresh token lifetime	Up to 14 days, rotated when used
Sliding window	Mailhub does not currently document the 14-day window as sliding
Turning Agent Access off	Stops new access, but not necessarily at that instant

Disabling Agent Access is not an instantaneous kill switch

If access must be stopped, disable Agent Access — but existing authorization may remain usable for up to about one hour, so do not treat the control as immediate revocation of everything already issued. For an urgent case, disable it and contact Mailhub.

See Authentication.

Not documented by this public contract

These are gaps in what Mailhub publishes, not findings about what Mailhub does internally. Absence of documentation here is not evidence that a mechanism does or does not exist — it means this public contract makes no claim either way, so a review should ask rather than infer.

• No claim about how tokens are stored. This page describes what authorization allows and how long it lasts, not the storage behind it.
• No customer-visible record of agent activity. Mailhub does not currently document a customer-facing history of MCP actions, or how long any internal record is kept.
• No claim that any MCP-capable client is supported. Support is confirmed by Mailhub per client, not inferred from protocol compatibility.
• No certification claim. Nothing here should be read as a compliance attestation for this feature.

Next

If your review needs an answer this page does not give, ask through the support arrangement in place for your account — Developer Support explains what to include.

• The authorization flow in detail: Authentication.
• Confirmation and money controls in full: Confirmations & Spend Safety.