Airpost
MCP server

Access levels

Choose what agents can do through airpost-mcp, and which accounts and folders they can see.

What airpost-mcp lets an agent do is set per profile, in Preferences > MCP in the desktop app or in <config-dir>/mcp.json. Every connected client gets the same access. The policy doesn’t apply to the airpost CLI, which always has full access (see Agent skill).

The three levels

LevelaccessLevelAllows
Read mailread-only (default)Listing, searching and reading mail, attachments, templates, tracking data, scheduled sends, events and contacts
Read and draftread-writeEverything above, plus drafts, archive, trash, move, labels, read and starred, snooze, reminders, undo, events without guests, and contacts
Read, draft and sendread-write-sendEverything above, plus send_draft, schedule_send, unsubscribe, respond_to_event, events with guests, and changing or deleting a meeting the account organizes that has guests

unsubscribe is in the send level because it can send mail. Events with guests are too, because the calendar server mails the guests. The tools reference lists the level each tool needs.

A call above the current level fails with “Access denied”. The agent is told to report what was refused and how to allow it, not to try another way. Give agents the lowest level the task needs.

How a call is checked

Every tool is tagged read, write or send, and airpost-mcp checks the tag against accessLevel before it contacts the engine. A few tools decide per call: create_event counts as send when it has attendees, and update_event, which also deletes events, counts as send when it gives attendees or the meeting is one the account organizes and has guests, because the calendar server mails them the change. The error names both levels:

{"error": "Access denied: 'write' operations require access level 'read-write', but current level is 'read-only'."}

Account and folder filters then apply to whatever the tool touches, whether it lists, reads or changes mail. A change to threads the agent can’t see fails as if the ids didn’t exist, so an agent can’t act on mail it can’t read.

Accounts and folders

By default agents can reach every account. In Preferences > MCP, under Mail apps can see, you can turn accounts off and use Choose folders to hide folders within an account.

A hidden account isn’t listed and its ids answer “not found”. Threads and messages in a hidden folder are hidden the same way, and the folder isn’t listed. A thread or message is hidden when any of its copies is in a hidden folder or label, even if another copy is in a folder you allow. On Gmail, hiding a label hides every thread that carries it.

Accounts you add later: when you’ve turned any account off, enabledAccounts lists accounts explicitly, and a new account that isn’t in the list is hidden until you turn it on.

Turning transports on and off

Under Local apps (stdio) in Preferences > MCP:

  • Allow apps over stdio turns off every stdio tool call when switched off, and hides every account from stdio clients. Calls then fail with “Access denied: apps on this computer are not allowed to use Airpost.”
  • Allow apps over HTTP controls the HTTP transport separately. Over HTTP, this switch alone decides whether tools run; a server still running after you switch it off refuses every call.

mcp.json

The desktop pane writes this file. You can also edit it by hand:

<config-dir>/mcp.json
{
  "enabled": true,
  "accessLevel": "read-only",
  "enabledAccounts": {
    "<accountId>": { "enabled": true, "excludedFolderIds": ["<folderId>"] }
  },
  "http": { "enabled": false, "port": 2587 }
}
accessLevelstringdefault:read-only

read-only, read-write or read-write-send. An unknown value is treated as read-only.

enabledAccountsobject

Empty or absent means every account. Otherwise an account that is absent, or has enabled: false, is hidden. excludedFolderIds lists folders to hide within an enabled account.

enabledbooleandefault:true

false refuses every stdio tool call. This is the Allow apps over stdio switch.

http.enabledbooleandefault:false

Whether airpost-mcp http serves. This is the Allow apps over HTTP switch.

http.portnumberdefault:2587

The HTTP port.

airpost-mcp reads the file again on every call, so changes apply on the next call without a restart. A file that doesn’t parse makes every tool fail, so a typo can’t widen access. The desktop pane refuses to edit a file that doesn’t parse.

Without mcp.json, airpost-mcp reads core.mcp.accessLevel and core.mcp.enabledAccounts from the profile’s config.json, where older versions of the desktop app kept them; HTTP stays off in that case. airpost-mcp status shows which source is in effect on its Policy: line.

On a server, AIRPOST_MCP_POLICY names a policy file to use in place of <config-dir>/mcp.json, so you can mount it read-only from outside the profile.