Angel Mail Docs

Connect your agent

Every agent reaches Angel Mail the same way: the MCP server at https://app.angelmail.io/mcp (on your own server, https://<your server>/mcp), over Streamable HTTP. There are two ways in.

Sign-inToken
ForThe apps listed below (Claude, ChatGPT, Codex, Cursor, VS Code, Grok, Gemini CLI, Hermes) and agents on your own computerEvery other app, device, script or server
HowThe app opens an Angel Mail page once; you approve it; the app keeps a refresh tokenYou make a token in Angel Mail → Settings → AI connections and put it in the app's settings
Headernone (the app handles it)Authorization: Bearer smt_…
Named in the queue asthe name you approve on the consent pagethe name you give the token

Either way, the agent works only as you, in your account, and only until you switch it off or revoke it in Settings → AI connections. Each agent shows up under its own name in Agent drafts, Agent proposals and the activity log.

The instruction for every agent #

Agents that have other mail tools (a Gmail connector, Composio, gog, Himalaya, Apple Mail) might use them instead and skip your review. Put this in each agent's own instructions; Settings → AI connections shows it with your name:

Email for the owner goes through Angel Mail (MCP server `angel-mail` (older setups: `sterling-mail`), or the `angel` command (older installs: `sterling`) where installed). To draft, reply to or send email for them, use its create_draft or request_send (revise_draft after they send one back). Never draft or send through Gmail, gog, Composio, Himalaya, Apple Mail or any other mail tool, even if one is available. Everything you write waits in Angel Mail → Agent drafts until the owner sends it; tell them it is there and give them the review_url. If Angel Mail isn't connected in this session, say so and stop rather than using another mail tool.

The server also sends its own instructions when an agent connects (MCP initialize), so a client that shows server instructions gets the same rule without the snippet.

Per app #

The examples use the hosted service. On your own server, put its address in place of https://app.angelmail.io. Where a block has smt_YOUR_TOKEN, make a token in Settings → AI connections and paste it there.

Codex #

The Codex app, CLI and IDE, and ChatGPT.

Codex #

Sign-in, no token. Once per Mac (the Codex app, CLI and IDE share it). In the Codex app: Settings → MCP servers → Add server → Streamable HTTP, name angel-mail, the URL below, Save, then Authenticate and Connect in the page that opens. Or run the lines below in Terminal. The first line removes an older entry (sterling-mail, or one with a pasted token), so Codex has the server once.

Terminal:

codex mcp remove sterling-mail
codex mcp add angel-mail --url https://app.angelmail.io/mcp
codex mcp login angel-mail

ChatGPT & Codex web #

Sign-in, no token. Once per ChatGPT account; it follows you to the web, the phone and Codex cloud. In ChatGPT: Plugins (or Settings → Apps & Connectors → Advanced → Developer mode) → create a plugin or connector, paste the URL below, choose OAuth, then Connect and approve in the page that opens.

MCP server URL:

https://app.angelmail.io/mcp

Codex plugin #

Sign-in, no token. On any Mac: add the Angel Mail marketplace once and install the plugin (the server and the instruction at the top of this page as a skill). Codex opens the sign-in page; approve it.

Terminal:

codex plugin marketplace add PirateKing44/sterling-mail-plugins
codex plugin add sterling-mail@sterling-mail

Claude #

Claude Code and the Claude app.

Claude Code #

Sign-in, no token. Once per Mac. Run the lines below (the first removes an older sterling-mail entry, so Claude Code has the server once), then in Claude Code type /mcp, pick angel-mail and choose Authenticate. Then put the instruction at the top of this page in ~/.claude/CLAUDE.md.

Terminal:

claude mcp remove --scope user sterling-mail
claude mcp add --scope user --transport http angel-mail https://app.angelmail.io/mcp

Claude app #

Sign-in, no token. Once per Claude account; it follows you to claude.ai, the desktop app and the phone. Settings → Connectors → Add custom connector, name Angel Mail, the URL below, Add, then Connect and approve.

Remote MCP server URL:

https://app.angelmail.io/mcp

Claude Code plugin #

Sign-in, no token. On any Mac, in Claude Code: add the Angel Mail marketplace once and install the plugin (it brings the server and the instruction at the top of this page as a skill). Then type /mcp, pick sterling-mail (the plugin's name for the server) and choose Authenticate.

In Claude Code:

/plugin marketplace add PirateKing44/sterling-mail-plugins
/plugin install sterling-mail@sterling-mail

Grok Bot #

Grok Bot and grok.com, as a connected app (or the angel command).

Grok Bot #

Sign-in, no token. Once per Grok account. In Grok Bot: Connect Apps → Add a custom MCP, paste the URL below as the Server URL (or ask Grok Bot in a chat to add it), then approve the Angel Mail page that opens and keep the name Grok Bot. Grok finds the tools by itself. Then add the instruction at the top of this page to the server's custom instructions in Grok Bot.

MCP server URL:

https://app.angelmail.io/mcp

grok.com #

Sign-in, no token. Once per Grok account, for Grok on the web and in its apps. grok.com/connectors → New Connector → Custom, paste the URL below, then approve the Angel Mail page that opens. Then add the instruction at the top of this page to Grok's custom instructions.

Connector URL:

https://app.angelmail.io/mcp

Shell (angel) #

With a token. For agents that run commands instead of MCP (Grok Bot, scripts). Install once: ln -sf <Angel Mail clone>/cli/sterling.mjs ~/.local/bin/angel (an older sterling link keeps working). Then sign in once with the token (kept in the macOS Keychain, or ~/.config/angel-mail/token elsewhere), and add the instruction at the top of this page to the agent.

Terminal:

angel login   # paste smt_YOUR_TOKEN
angel draft --to someone@example.com --subject "Hello" --body-file note.md
angel drafts

Cursor #

Cursor's editor and agents, VS Code and Windsurf; any other app with a token.

Cursor #

Sign-in, no token. Once per computer. Cursor → Settings → MCP & Integrations → New MCP server (it opens ~/.cursor/mcp.json), add the block below and save. Cursor shows the server as needing sign-in: click Connect (or Login) and approve the Angel Mail page that opens; it comes back to Cursor by itself. Then put the instruction at the top of this page in Cursor's rules (Settings → Rules).

~/.cursor/mcp.json:

{
  "mcpServers": {
    "angel-mail": {
      "url": "https://app.angelmail.io/mcp"
    }
  }
}

VS Code #

Sign-in, no token. Once per computer, for VS Code's agent mode (and Copilot). Run the line below, then start the server in VS Code (MCP: List Servers → angel-mail → Start) and allow the sign-in it asks for. Windsurf signs in the same way; any other editor connects with a token (Any other MCP client).

Terminal:

code --add-mcp '{"name":"angel-mail","type":"http","url":"https://app.angelmail.io/mcp"}'

Any other MCP client #

With a token. Streamable HTTP, one JSON-RPC message per POST (no SSE stream needed). Sign-in is only for the apps listed here and agents on this computer; any other app or device connects with a token of its own: Make a token in Angel Mail → Settings → AI connections, give it a name you'll recognise, and put the URL and header in the app's MCP settings. The token works only for this server and only until you revoke it in Settings → AI connections; its name is what you'll see in Agent drafts.

URL and header:

https://app.angelmail.io/mcp
Authorization: Bearer smt_YOUR_TOKEN

Uriel #

Your Uriel workspace and the agents it runs, with a token.

Uriel #

With a token. Once per Uriel. Make a token in Angel Mail → Settings → AI connections, then in Uriel: Settings → Tools → Add (Import from JSON), paste the block below and save. Switch it on for the agents that should work in your mail (Claude Code, Codex and the others Uriel runs). A Uriel chat can add it for you too: give it the block and ask it to add the MCP server. Then put the instruction at the top of this page in Uriel's assistant rules.

Import from JSON:

{
  "mcpServers": {
    "angel-mail": {
      "type": "http",
      "url": "https://app.angelmail.io/mcp",
      "headers": {
        "Authorization": "Bearer smt_YOUR_TOKEN"
      }
    }
  }
}

Hermes #

The Hermes agent on your Mac.

Hermes #

Sign-in, no token. Once per Mac. Run the lines below (the first removes an older sterling-mail entry, or one with a pasted token); Hermes opens the sign-in page. Check with hermes mcp test angel-mail, then put the instruction at the top of this page in ~/.hermes/SOUL.md.

Terminal:

hermes mcp remove sterling-mail
hermes mcp add angel-mail --url https://app.angelmail.io/mcp --auth oauth

Google Gemini CLI #

Google's Gemini CLI agent.

Gemini CLI #

Sign-in, no token. Once per Mac. Run the lines below (the first removes an older sterling-mail entry), then in Gemini CLI type /mcp auth angel-mail and approve the sign-in page it opens. Then put the instruction at the top of this page in ~/.gemini/GEMINI.md.

Terminal:

gemini mcp remove --scope user sterling-mail
gemini mcp add --scope user --transport http angel-mail https://app.angelmail.io/mcp

Gemini CLI extension #

Sign-in, no token. On any Mac: install the extension (the server and the instruction at the top of this page) and answer yes when Gemini asks to trust it. Then in Gemini CLI type /mcp auth sterling-mail (the extension's name for the server) and approve the sign-in page.

Terminal:

gemini extensions install https://github.com/PirateKing44/sterling-mail-plugins

Permissions a token can have #

Set per connection in Settings → AI connections:

SettingOff (default)On
Can sendsend_approved_email isn't offered. Everything waits for you to press Send in Angel MailThe agent may send an email after you said yes to its exact preview in the conversation, within 2 hours
May do on its own: mark read / unreadProposed for your approvalDone at once
May do on its own: star / unstarProposed for your approvalDone at once
May do on its own: add labelsProposed for your approvalDone at once
On / off switchThe server answers 403 until you switch it back onNormal

Archive, trash, unsubscribe and replies always wait for your approval, whatever the token may do. See Safety and permissions.

Check the connection #

Ask the agent to list your inboxes; it calls list_accounts. Or from a shell, with your token in ANGEL_MAIL_TOKEN:

curl -s https://app.angelmail.io/mcp \
  -H "Authorization: Bearer $ANGEL_MAIL_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_accounts","arguments":{}}}'

MCP over HTTP has the whole protocol.

For agents: this page as Markdown, every page in one file at llms-full.txt, the index at llms.txt.