# 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-in | Token |
| --- | --- | --- |
| **For** | The apps listed below (Claude, ChatGPT, Codex, Cursor, VS Code, Grok, Gemini CLI, Hermes) and agents on your own computer | Every other app, device, script or server |
| **How** | The app opens an Angel Mail page once; you approve it; the app keeps a refresh token | You make a token in Angel Mail → Settings → AI connections and put it in the app's settings |
| **Header** | none (the app handles it) | `Authorization: Bearer smt_…` |
| **Named in the queue as** | the name you approve on the consent page | the 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.

> **Older setups.** Before the rename the server key was `sterling-mail` and the command `sterling`. They keep working. The steps below remove an older entry first, so the server is listed once.

## 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:

<!-- generated:rule -->
```text
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.
```
<!-- /generated:rule -->

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.

<!-- generated:connect -->
### 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:

```bash
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:

```text
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:

```bash
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:

```bash
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:

```text
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:

```bash
/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:

```text
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:

```text
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:

```bash
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:

```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:

```bash
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:

```text
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:

```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:

```bash
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:

```bash
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:

```bash
gemini extensions install https://github.com/PirateKing44/sterling-mail-plugins
```
<!-- /generated:connect -->

## Permissions a token can have

Set per connection in Settings → AI connections:

| Setting | Off (default) | On |
| --- | --- | --- |
| **Can send** | `send_approved_email` isn't offered. Everything waits for you to press Send in Angel Mail | The 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 / unread** | Proposed for your approval | Done at once |
| **May do on its own: star / unstar** | Proposed for your approval | Done at once |
| **May do on its own: add labels** | Proposed for your approval | Done at once |
| **On / off switch** | The server answers 403 until you switch it back on | Normal |

Archive, trash, unsubscribe and replies always wait for your approval, whatever the token may do. See [Safety and permissions](safety.md).

## 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`:

```bash
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](protocol.md) has the whole protocol.
