---
name: unitpost-agent-setup
title: Onboard your agent to Unitpost
description: |-
  Hand your coding agent this playbook to set up Unitpost: add the
  Unitpost skill, connect the hosted MCP server with OAuth, and sign in to
  the CLI.
supported_surfaces: [skills, mcp, cli]
url: https://www.unitpost.com/agent-setup.md
---

# Set up Unitpost for your AI agent

These are the official Unitpost setup instructions for AI coding agents.
Unitpost is an API for transactional email, marketing email and SMS. When
you finish, the agent has the Unitpost skill (how the API works), the MCP
server (tools that act in the user's workspace) and the `unitpost` CLI (for
scripts and CI).

## How to run

Run sections 1 and 3 once per machine. Run section 2 once for each agent the
user wants connected. Do the work yourself when you have terminal or file
access: don't hand the user commands to copy. Install at user (global) scope
unless the user asks for a single project.

Pause only for what you can't do: the user signing in and approving access in
the browser, or a click in an app's settings. If a step is blocked, note why
and carry on with the next one. The npm routes below need Node.js 20 or newer.

Before you change a config file, read it and merge one `unitpost` entry. Keep
everything else. During setup, don't send email or SMS, create API keys, or
change workspace settings.

## 1. Add the Unitpost skill

```sh
npx -y skills add unitpostcom/skills --skill unitpost --global --yes
```

The `skills` CLI writes the skill into every agent it finds on this machine.
Note the path its summary reports (usually `~/.agents/skills/unitpost`). It may
also list an agent that refused a global install (PromptScript does): that is
expected and doesn't block the others.

## 2. Connect the Unitpost MCP server

The server is remote (Streamable HTTP):

```text
https://mcp.unitpost.com/mcp
```

It signs in with OAuth: the user picks a workspace and approves access in the
browser, and tokens refresh on their own. No API key goes in the config. Use
the route for your client below. If your client only runs stdio servers, use
command `npx` with args `["-y", "mcp-remote", "https://mcp.unitpost.com/mcp"]`.

### Claude Code

```sh
claude mcp list
claude mcp add --transport http --scope user unitpost https://mcp.unitpost.com/mcp
```

Then ask the user to run `/mcp` in Claude Code, select **unitpost**, and choose
**Authenticate**.

### Codex

```sh
codex mcp list
codex mcp add unitpost --url https://mcp.unitpost.com/mcp
```

Codex detects OAuth and opens the browser to sign in. If `unitpost` already
exists and `codex mcp list` shows `Not logged in`, run
`codex mcp login unitpost`. The Codex CLI, IDE extension and app share this
config, so one setup covers all three.

### Cursor

Merge into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "unitpost": { "url": "https://mcp.unitpost.com/mcp" }
  }
}
```

Cursor marks the server **Needs login**. Ask the user to click it.

### VS Code with GitHub Copilot

```sh
code --add-mcp '{"name":"unitpost","type":"http","url":"https://mcp.unitpost.com/mcp"}'
```

Without the `code` command, ask the user to run **MCP: Add Server**, choose
**HTTP**, paste the URL, name it `unitpost` and pick **Global**. Then start it
from **MCP: List Servers** and allow sign-in.

### Gemini CLI

Merge into `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "unitpost": { "httpUrl": "https://mcp.unitpost.com/mcp" }
  }
}
```

Then ask the user to run `/mcp auth unitpost` in Gemini CLI.

### OpenCode

Merge under `"mcp"` in `~/.config/opencode/opencode.jsonc`:

```json
"unitpost": { "type": "remote", "url": "https://mcp.unitpost.com/mcp", "oauth": {} }
```

Then run `opencode mcp auth unitpost`.

### Windsurf

Merge into `~/.codeium/windsurf/mcp_config.json` (`serverUrl`, not `url`):

```json
{
  "mcpServers": {
    "unitpost": { "serverUrl": "https://mcp.unitpost.com/mcp" }
  }
}
```

Refresh the MCP servers in Windsurf. Sign-in opens on first use.

### Other clients

Add the URL as a remote HTTP server with no headers. Clients that follow the
MCP spec find the OAuth flow from the first `401`. Chat apps (Claude,
ChatGPT) connect in their own settings: ask the user to add the URL as a custom
connector. With no browser on this machine (SSH, CI), ask the user for an API
key and follow https://www.unitpost.com/docs/ai/headless. Never write a key into a file
tracked by git.

### Sign in and verify

Before the user approves, check the server URL in the client's config is
exactly `https://mcp.unitpost.com/mcp`. The approval page itself opens on `https://www.unitpost.com`: tell the
user to approve only there. It lists every permission ticked; they can untick
any they don't want. Wait while they finish in the browser, then call the
read-only `email_domains_list` tool. An
empty list passes. If the tools are missing, refresh the client's MCP servers,
and restart the client only if that doesn't load them.

Leave confirmation on for every tool that sends (`email_send`,
`email_send_batch`, `email_campaigns_send`, `email_campaigns_resume`,
`sms_send`, `sms_campaigns_send`, `sms_campaigns_resume`) and every tool the
client marks destructive (deletes, cancels, suppressions). Never add them to an
auto-approve list: they reach real people or can't be undone.

## 3. Install the Unitpost CLI

Check whether it's already installed:

```sh
unitpost --version
```

If it's missing, use the first route that works on this machine. Homebrew and
the install script give a standalone binary that needs no Node.js; the script
checks the download's SHA-256 before installing.

```sh
brew install unitpostcom/tap/unitpost        # macOS or Linux with Homebrew
curl -fsSL https://www.unitpost.com/install.sh | sh     # macOS or Linux, no Homebrew
npm install --global unitpost-cli             # anywhere with Node.js 20+
```

On Windows, in PowerShell:

```powershell
irm https://www.unitpost.com/install.ps1 | iex
```

The install script puts `unitpost` in `~/.unitpost/bin` and prints the line
that adds it to PATH: run that line as well. If every route fails, skip this
section and report why. Otherwise sign in and confirm:

```sh
unitpost login
unitpost whoami
```

Run `unitpost login` as is, with no `--scope`: it asks for every permission
the CLI's commands use (the same set as MCP), and the user can untick any of
them on the approval page. It uses the same browser approval as MCP and keeps
the token in the macOS Keychain (a private file on other systems).

On a remote shell (SSH), run `unitpost login --no-browser` in a terminal the
user can type into, and give them the URL it prints. After they approve, their
browser lands on an `http://127.0.0.1:…/callback` address that won't load:
they paste that address into the terminal. If you can't give them that
terminal, ask them for an API key instead (`unitpost login --key`). The user
sees and revokes every CLI and MCP sign-in in Settings → Connected apps.

Don't add the SDK or write sending code during setup. Do that when the user
asks to send from their app.

## Report

Report only what you verified:

```text
Unitpost agent setup
Skill:  <path | blocked: reason>
MCP:    <connected | waiting for sign-in | blocked: reason>, <client>, <config path>
Check:  <email_domains_list ok | not run: reason>
CLI:    <version, signed in to <workspace id>, <n> permissions | blocked: reason>
Manage: Settings → Connected apps (see or revoke these sign-ins)
Reload: <not needed | restart <client> to load MCP>
```

## Resources

- Agent docs and per-client MCP guides: https://www.unitpost.com/docs/ai
- Skill source: https://github.com/unitpostcom/skills
- CLI: https://www.unitpost.com/docs/cli
- Authentication for agents: https://www.unitpost.com/auth.md
- System status (check it first when calls fail across the board): https://status.unitpost.com

This playbook is published at https://www.unitpost.com/agent-setup.md, so you can check it again at any time.