Authentication

You do not configure any of this by hand — your MCP client and Mailhub settle it between themselves. It decides who the assistant is, what it may do, and for how long.

How you authorize an assistant

1. The MCP client starts the authorization. It cannot mint access on its own.
2. Mailhub opens the normal sign-in in your browser. Not a special MCP login — the same one you use for the Mailhub application. There is no MCP-specific password, no API key, and no service account.
3. Two-factor authentication applies if it is enabled for your user. The MCP layer adds no second factor of its own and removes none.
4. You reach the MCP consent screen and either approve or deny. The consent screen names the client and the access it is asking for. Denying returns you to the client empty-handed; nothing is granted and nothing is changed.
5. After approval the client can call tools — inside Agent Access and inside your own permissions, not beyond them.

Agent Access

Agent Access is an account-level switch, and it is off until someone turns it on. Turning it on requires permission to manage the account's integrations.

Approving access and enabling it are two different acts

A user without integration-management permission can complete the whole browser authorization successfully. The connection looks healthy — and every tool call is then refused until someone who does have that permission enables Agent Access for the account. An assistant that connects and can do nothing at all is the usual shape of this.

Agent Access governs the account, not the individual user: it does not replace anyone's permissions, and it does not grant any. It decides only whether this account allows agents at all.

The assistant acts as the Mailhub user who authorized it and carries that user's existing roles and permissions — what you cannot do in the Mailhub application, the assistant cannot do for you. Two gates therefore stand between an assistant and any Mailhub operation, and both must be open: Agent Access on the account, and the permission on your user. Before You Connect lists which permission each tool needs.

Technical OAuth contract

Protocol	OAuth 2.1
Grant	Authorization Code, with Refresh Token for renewal
PKCE	Required. Mailhub refuses an authorization without it
Client type	Public
Client secret	None. A public client holds no secret, so PKCE carries the protection a secret would otherwise give
Client id	mailhub-claude-mcp
Scope	mcp.tools
Registration	By Mailhub, in advance

A public client is one that cannot keep a secret — a desktop or user-facing application, not a server you control. It does not mean a client anyone may register.

The client id is not a credential you act on

mailhub-claude-mcp is published so you can recognize it, not so you can register with it. It is not a self-registration credential, and it is not proof that any particular assistant product or environment is supported. Mailhub does not implement dynamic client registration, so an MCP client cannot register itself; only a client Mailhub has registered in advance can complete an authorization, and a client that is otherwise MCP-capable still cannot connect without that registration.

Session lifetime and stopping access

Access tokens are valid for 60 minutes. Refresh tokens are valid for up to 14 days and are rotated when used. Mailhub does not currently document the 14-day window as sliding, so treat an eventual request to sign in again as normal rather than as a fault.

Disabling Agent Access stops new MCP tool access, but the effect is not necessarily immediate. Existing authorization may remain usable for up to about one hour.

Turning Agent Access off is not an emergency stop

If you need access to end this second — a compromised device, a client you no longer trust — turn Agent Access off and raise it with Mailhub through the support arrangement in place for your account, and treat the window above as real. Disabling the switch is the right control for "we are done with this", not for "stop it now".

Removing or restricting the authorizing user's Orders permissions narrows what an assistant can do in the same way it narrows what that user can do. If an assistant keeps being asked to sign in again, the cause may be Agent Access or the user's account access rather than an expired session — Errors & Troubleshooting covers how to tell them apart.

Consent does not bypass account controls

Authentication establishes who is acting: your Mailhub sign-in, your 2FA, your consent. Authorization decides what that identity may do: Agent Access on the account, your roles and permissions, the explicit confirmation each changing tool requires, and the account's agent spend limit.

Approving the consent screen answers only the first. Nearly every "it connected but nothing works" report is the second — see Confirmations & Spend Safety for the confirmation and spend controls.

For client developers

You do not perform these steps; a compliant MCP client does them. They are described here because they explain why a client either connects cleanly or cannot connect at all — none of it is actionable without a client Mailhub has already confirmed.

• The MCP server publishes OAuth protected-resource metadata. A client that calls the server without valid access is told where that metadata is.
• The metadata names the authorization server to use and the scope the server requires, which is mcp.tools.
• The client then runs the Authorization Code flow with PKCE against that authorization server.
• The access token that comes back is audience-bound to the Mailhub MCP server. It is not a general Mailhub credential and is not accepted anywhere else.

A client that cannot follow this discovery, or cannot do PKCE, cannot connect — and no amount of configuration on your side changes that.

Next

Read Confirmations & Spend Safety — what a confirmed change still has to clear before it runs.

• Looking up what a tool takes and returns? Tool Reference.
• An account not behaving as described here? Developer Support.