Agents

Postage hosts an MCP server on your Mac. Any MCP-aware agent can read and organize your mail through it, using the account the agent is already signed in to. Postage never asks you for an agent subscription or key.

How it works

The server listens on http://127.0.0.1:47913/mcp. Localhost only, default port 47913, changeable under Advanced. Nothing is exposed to your network.
Postage gives each client its own bearer token, stored in your Keychain. Revoke one and only that client loses access.
Any number of clients can be connected at once. Postage lists them with the last time each was seen.
Postage fills your token into the commands below when you open Integrations. The snippets here use a placeholder.

Access levels

Set per client. The server enforces it: a tool outside the level is not listed to the agent and is refused if called anyway.

Read only

The agent can look, and nothing else.

Can

List your accounts and folders
Search and read messages and threads
See unread counts

Cannot

Change, move or delete anything
Create drafts
Send

Read + organize

The agent can tidy your mail, and nothing leaves your outbox.

Can

Everything in Read only
Mark read or unread, flag, archive, move, mark as junk

Cannot

Delete
Write drafts
Send

Full

Everything, with a person in the loop for sending.

Can

Everything in Read + organize
Delete (moves to Trash)
Write drafts
Ask to send a message

Cannot

Send without you. Every send opens a confirmation sheet in Postage with Send, Edit and Cancel.

Sending is always approved

When an agent asks to send a message, Postage opens a confirmation sheet showing the sender, recipients and body. You choose Send, Edit or Cancel, and the agent receives the outcome. There is no setting that turns the sheet off. Drafts do not need confirmation, because nothing leaves your Mac until you send.

Setup by client

Replace YOUR_POSTAGE_TOKEN with the token Postage shows for that client. In Postage, open Integrations, pick the client and use Copy, or the one-click install where the client supports it. Connected clients show up in the list once they have initialized.

Claude Code

Runs in your terminal on your Claude account. One command adds Postage for every project, or just this one.

Terminal

claude mcp add --transport http --scope user postage http://127.0.0.1:47913/mcp \
  --header "Authorization: Bearer YOUR_POSTAGE_TOKEN"

Codex CLI

Uses your ChatGPT sign-in. Put the token in an environment variable and point Codex at it.

~/.codex/config.toml

[mcp_servers.postage]
url = "http://127.0.0.1:47913/mcp"
bearer_token_env_var = "POSTAGE_MCP_TOKEN"

Shell profile

export POSTAGE_MCP_TOKEN=YOUR_POSTAGE_TOKEN

Claude Desktop

Claude Desktop talks to local servers through a small bridge, so the config runs mcp-remote.

claude_desktop_config.json

{
  "mcpServers": {
    "postage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:47913/mcp", "--header", "Authorization:${POSTAGE_AUTH}"],
      "env": { "POSTAGE_AUTH": "Bearer YOUR_POSTAGE_TOKEN" }
    }
  }
}

Cursor

Postage can open Cursor's install prompt for you, or you can paste this into mcp.json.

~/.cursor/mcp.json

{
  "mcpServers": {
    "postage": {
      "url": "http://127.0.0.1:47913/mcp",
      "headers": { "Authorization": "Bearer YOUR_POSTAGE_TOKEN" }
    }
  }
}

VS Code

Works with Copilot agent mode and any other MCP-aware extension.

.vscode/mcp.json

{
  "servers": {
    "postage": {
      "type": "http",
      "url": "http://127.0.0.1:47913/mcp",
      "headers": { "Authorization": "Bearer YOUR_POSTAGE_TOKEN" }
    }
  }
}

Windsurf

Add Postage as a custom MCP server.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "postage": {
      "serverUrl": "http://127.0.0.1:47913/mcp",
      "headers": { "Authorization": "Bearer YOUR_POSTAGE_TOKEN" }
    }
  }
}

Zed

Zed lists MCP servers as context servers.

Zed settings.json

{
  "context_servers": {
    "postage": {
      "url": "http://127.0.0.1:47913/mcp",
      "headers": { "Authorization": "Bearer YOUR_POSTAGE_TOKEN" }
    }
  }
}

Gemini CLI

Uses your Google sign-in.

~/.gemini/settings.json

{
  "mcpServers": {
    "postage": {
      "httpUrl": "http://127.0.0.1:47913/mcp",
      "headers": { "Authorization": "Bearer YOUR_POSTAGE_TOKEN" }
    }
  }
}

AI inside Postage

Rules and summaries use their own AI mode, separate from the agents above.

Apple Intelligence

Runs on your Mac with Apple's on-device model. No account, no key, no network.

Access: Reads the message it is working on. Nothing leaves your Mac. Needs a Mac that supports Apple Intelligence.

Your own API key

Anthropic, OpenAI, or any OpenAI-compatible endpoint. The key is stored in your Keychain.

Access: Sends the message text to the provider you chose, only when a rule or summary needs it. Postage asks for your consent before the first time it does.

Agents over MCP

Claude Code, Codex, Claude Desktop, Cursor and the rest connect to Postage and use the sign-in they already have.

Access: Limited to the access level you set for each client. Message bodies are marked as untrusted content so an email cannot give your agent orders.