Connection grant
A connection grant is the OAuth authorisation a human approves in a browser so an agent client may call MCP tools on named inboxes, expiring after 30 days and revocable without rotating any shared secret.
There are two ways to give an agent access to an inbox here, and only one of them
involves a human looking at a screen that names exactly what is being granted. A
connection grant is that one. It is what the remote MCP endpoint at
https://mcp.emailforagents.ai/mcp accepts, and it is the only thing that endpoint
accepts.
What the human is actually agreeing to
The consent step resolves three decisions at once.
A project. A connection binds to a single project, the first on the grant. There is no cross-project tool and no argument that selects one, so a connected agent’s reach is bounded before any tool is called.
A set of inboxes. Chosen at consent time, not inherited from the workspace.
A preset. Three OAuth scope strings map to three presets: email.read to read,
email.draft to read_draft, and email.send to read_draft_send. Those resolve
to concrete scope sets. read carries inboxes:read, threads:read,
messages:read, attachments:read and events:read. read_draft adds
drafts:read, drafts:write and drafts:submit. read_draft_send adds
messages:send and nothing else.
read_draft is where almost every integration should start, and the reason is
structural rather than advisory. A principal holding drafts:submit without
messages:send always gets approval_required back, whatever the inbox policy says.
The agent can compose a complete, well-formed reply and cannot transmit one.
Why an API key will not work here
The /mcp endpoint rejects efa_ keys and browser session tokens with HTTP 401 and
a WWW-Authenticate: Bearer realm="mcp" challenge. Only a connection grant token
works.
This is a design decision rather than an oversight, and it is worth understanding before you try to route around it. A key is a secret that a developer pasted somewhere. A connection grant is a record that a specific human, at a specific time, read a screen naming a project, a set of inboxes and a preset, and agreed to it. On a surface where the client is an agent the mailbox owner installed themselves, the second record is the one worth having, and accepting both would mean the weaker one is always available. Remote MCP or a REST key sets out when each route is the right shape.
Lifetime and revocation
A connection is created with an expiry 30 days out. Revocation is the meaningful
difference from a key: there is no secret in the agent’s possession to rotate, no
config file to edit, and no deployment to redo. Revoke the connection and the next
tools/list returns nothing the grant no longer covers, because scopes are re-read
from current state rather than carried in the token.
The same mechanism narrows a grant without revoking it. Reduce the authorising human’s role and every connection they approved narrows on the next call, with no cached-token window in between.
What a connection grant cannot carry
Eight scopes cannot be attached to a connection at any preset: keys:manage,
members:manage, billing:manage, policies:write, inboxes:delete,
messages:delete, messages:raw and exports:write. A connected agent therefore
cannot mint a credential, change an inbox policy, or delete the record of what it
did. The audit trail is deliberately out of reach of the thing being audited.
It also cannot do three things the REST API can: upload attachment bytes, manage webhooks, and replay an event cursor. Those absences are why teams that run their own service usually hold both a connection grant for a human’s agent client and a project key for their own ingestion path. The two surfaces are described side by side on the integrations page.
One more limit, because it changes how you write tool calls: a tool result over 131,072 characters is replaced with an error pointing at the scoped REST API. A connection grant is not a bulk export route, and nothing about it is one-click. Whether any particular MCP client works is a question about that client, and none are certified or supported here.