Agents

Skills

The skill is documentation an agent loads on demand: endpoints, ID prefixes, scopes, pagination, and send-safety rules. It is not a live connection and it contains no secrets. Install it, then give the agent a key at runtime.

npx skills add unitpostcom/skills --skill unitpost
npx skills add unitpostcom/skills --skill unitpost -g

MCP

The MCP server is the live tool surface. One tool per API operation. Connect in the browser with OAuth, or paste a key for headless clients.

Cursor

Add the server URL and approve in the browser (Cursor handles OAuth itself, including reconnect). Static key config still works as a fallback.

1. 1

   Connect with OAuth (recommended)

   Add a remote server with the URL below — Cursor opens Unitpost in the browser to approve. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically. If Cursor ever signs you out, the Authenticate button re-runs the same approval (a 401 from us triggers its reconnect).

   JSON

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

   Prefer this over pasting secrets. To pin credentials instead, add an auth object with CLIENT_ID: cursor-oauth (public client, PKCE — no secret needed).

2. 2

   Reload and verify

   Reload MCP servers in Cursor. unitpost should show connected with tools like email_send, email_campaigns_send, email_domains_verify.

3. 3

   Send a test

   Ask the agent to send a test email from a verified domain, then confirm it in Unitpost Activity.

Claude Code

Add the server URL, then authenticate from the in-session MCP panel. The browser opens at the Authenticate step, not at add time. API keys still work as a fallback.

1. 1

   Add the server

   Run once. This only saves the URL — no browser opens yet.

   Shell

   claude mcp add --transport http unitpost https://mcp.unitpost.com/mcp

   Use -s user to install for every project. claude mcp list now shows unitpost as ! Needs authentication — that is expected.

2. 2

   Authenticate with OAuth (recommended)

   Start a Claude Code session, run /mcp, select unitpost, and choose Authenticate. Your browser opens to Unitpost — pick a workspace, approve the scopes, and you're connected. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   If the browser doesn't open automatically, copy the URL shown in the terminal and open it manually. Tokens refresh automatically; if auth ever lapses, repeat this step.

3. 3

   Verify

   Run claude mcp list (or /mcp in a session). unitpost should show connected with its tools listed — no ! Needs authentication flag.

   Don't see it? Fully quit and reopen the client — closing the window is often not enough — then check again.

4. 4

   Send a test

   Ask Claude to send an email from a verified domain and confirm it in Unitpost Activity.

Claude Desktop

Claude Desktop connects with OAuth: add the server URL, approve in the browser, done. No browser or older plan? The headless guide has the mcp-remote bridge config.

1. 1

   Add a custom connector (recommended)

   In Claude Desktop: Settings → Connectors → Add custom connector. Paste the server URL below as the Remote MCP server URL and complete the browser approval. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   Remote MCP server URL	https://mcp.unitpost.com/mcp

2. 2

   Verify

   The unitpost connector should show as connected with its tools available in chat.

   Don't see it? Fully quit and reopen the client — closing the window is often not enough — then check again.

3. 3

   Send a test

   Ask Claude to send an email from a verified domain and confirm it in Unitpost Activity.

Codex

In ChatGPT, add the server URL as a connector and approve in the browser. The Codex CLI reads static config only (no browser flow) — its key setup lives on the headless page.

1. 1

   Connect with OAuth (recommended)

   In ChatGPT, open the MCPs tab and connect a custom MCP. Select Streamable HTTP (not STDIO), paste the server URL below, then complete the browser approval. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   MCP server URL	https://mcp.unitpost.com/mcp

2. 2

   Verify

   The unitpost connector should show as connected with its tools available. Codex CLI users: the CLI can't do the browser flow — follow the headless guide instead.

   Adding a connector requires a restart before chats see it: restart the Codex app, then check /mcp. Don't see it? Fully quit and reopen the client — closing the window is often not enough — then check again.

3. 3

   Send a test

   Ask Codex to send an email from a verified domain and confirm it in Unitpost Activity.

GitHub Copilot

Add the server URL and approve in the browser. If your setup needs a static key, VS Code prompts for it at runtime (never stored in the file).

1. 1

   Connect with OAuth (recommended)

   Create or edit `.vscode/mcp.json` in your workspace (or MCP: Add Server from the Command Palette for a user-level entry) with the server URL below, then start it. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   JSON

   {
     "servers": {
       "unitpost": {
         "type": "http",
         "url": "https://mcp.unitpost.com/mcp"
       }
     }
   }

   VS Code tries HTTP streamable first, then OAuth on 401 (DCR). Official redirects we allow: https://vscode.dev/redirect and http://127.0.0.1:33418.

2. 2

   Start the server

   Open the MCP view and start unitpost. Complete the browser approval, then confirm tools are listed. If it disconnects later, restart it here.

3. 3

   Send a test

   In Copilot agent mode, ask it to send a test email from a verified domain and confirm in Unitpost Activity.

Gemini CLI

Prefer the OAuth browser approval. If your setup needs static config, paste the key block instead.

1. 1

   Connect with OAuth (recommended)

   Add this block to `~/.gemini/settings.json` (no headers — Gemini discovers OAuth from the 401). No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   JSON

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

2. 2

   Verify

   Restart the Gemini CLI and run /mcp. unitpost should list its tools. If it shows as needing authentication, run /mcp auth unitpost — the browser opens for approval, and tokens refresh automatically after that.

3. 3

   Send a test

   Ask Gemini to send an email from a verified domain and confirm it in Unitpost Activity.

Windsurf

Prefer the OAuth browser approval. If your setup needs static config, paste the key block instead.

1. 1

   Connect with OAuth (recommended)

   In Windsurf: Settings → Cascade → MCP Servers → Add Server, or paste this into `~/.codeium/windsurf/mcp_config.json`. Windsurf uses serverUrl (not url) for remote HTTP. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   JSON

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

2. 2

   Refresh and verify

   Refresh the MCP server list. Unitpost's tools should appear under unitpost.

3. 3

   Send a test

   Ask Cascade to send a test email from a verified domain, then confirm in Unitpost Activity.

OpenCode

OpenCode auto-detects OAuth on 401 (DCR). Add a remote server and run `opencode mcp auth unitpost`.

1. 1

   Add the remote server

   Put this in ~/.config/opencode/opencode.jsonc (or project opencode.json). No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   JSON

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "unitpost": {
         "type": "remote",
         "url": "https://mcp.unitpost.com/mcp",
         "oauth": {}
       }
     }
   }

2. 2

   Authenticate

   Restart OpenCode, then run opencode mcp auth unitpost (or wait for the first tool call). Complete the browser approval.

3. 3

   Verify

   Run opencode mcp list. unitpost should show connected.

4. 4

   Send a test

   Ask the agent to send a test email from a verified domain and confirm it in Unitpost Activity.

Grok

In Grok: add a custom connector with the name and URL below, then approve in the browser. The xAI marketplace plugin lives at github.com/unitpostcom/unitpost-grok-plugin (catalog PR on hold until Connect is verified).

1. 1

   Connect with OAuth (recommended)

   Add a custom connector. Name it Unitpost, paste the server URL below (the /mcp URL — streamable HTTP — not an /sse URL). No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   Name	Unitpost
   Server URL	https://mcp.unitpost.com/mcp

   Text

   https://mcp.unitpost.com/mcp

   Don't see it? Fully quit and reopen the client — closing the window is often not enough — then check again.

2. 2

   Send a test

   Ask Grok to send a test email from a verified domain and confirm it in Unitpost Activity.

Generic / custom client

Any streamable-HTTP MCP client that speaks MCP OAuth connects with just the URL. Anything else uses a Bearer API key.

1. 1

   Connect with OAuth (recommended)

   Point the client at the server URL below. A spec-compliant client discovers OAuth itself: it reads the WWW-Authenticate: Bearer resource_metadata="…" challenge on the first 401, fetches /.well-known/oauth-protected-resource, runs the PKCE code flow against the advertised authorization server, and retries with the token. No key to copy. Your client opens Unitpost in the browser — pick a workspace, approve the scopes, and you're connected. Tokens refresh automatically.

   Server URL	https://mcp.unitpost.com/mcp
   Transport	Streamable HTTP
   Auth (recommended)	OAuth 2.1 — add the URL, approve in the browser
   Auth (legacy)	Authorization: Bearer pk_live_YOUR_KEY
   Tools	one per API operation (email_send, email_campaigns_send, …)

2. 2

   Discover tools

   The server advertises one tool per API operation (email_send, email_campaigns_send, email_domains_verify, …). A write's body maps to the API request body. Every tool declares securitySchemes: [{ type: "oauth2", scopes: […] }] so linking-aware clients (ChatGPT) show the Connect UI.

3. 3

   Verify

   Call a read tool (e.g. list domains). An unauthenticated call answers 401 with a WWW-Authenticate: Bearer resource_metadata="…" challenge (start OAuth there). With a key, a 401 Invalid API key usually means a missing Bearer prefix or a mistyped key — recreate the key and retry.

   Don't see it? Fully quit and reopen the client — closing the window is often not enough — then check again.

Headless / API key

OAuth needs a browser. Where there isn't one — CI jobs, SSH sessions, containers, Codex CLI, or any client that can only paste a static header — send a workspace API key as the Bearer token instead. Same scopes, same gates, same tools.

1. 1

   Create an API key

   Open https://www.unitpost.com → Settings → API keys → create a scoped key. Copy the full pk_live_… value (shown once). In every snippet below, replace pk_live_YOUR_KEY with that value.

   Shown once. Keep the Bearer prefix in every snippet. Grant only the scopes the agent needs (e.g. emails:send for email_send). Prefer a revocable key dedicated to the agent.

2. 2

   Cursor (static key)

   Edit `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (this project only) — or Cursor Settings → MCP → Add new MCP server. Put the unitpost entry under top-level mcpServers.

   JSON

   {
     "mcpServers": {
       "unitpost": {
         "url": "https://mcp.unitpost.com/mcp",
         "headers": {
           "Authorization": "Bearer pk_live_YOUR_KEY"
         }
       }
     }
   }

3. 3

   Claude Code (static header)

   Flags stay before the name/URL.

   Shell

   claude mcp add --transport http --header "Authorization: Bearer pk_live_YOUR_KEY" unitpost https://mcp.unitpost.com/mcp

4. 4

   Claude Desktop (mcp-remote bridge)

   For plans without custom connectors. In Claude Desktop: Settings → Desktop app → Developer → Edit Config, then merge the block below — mcpServers must be a top-level key (sibling of preferences), not nested inside it.

   JSON

   {
     "mcpServers": {
       "unitpost": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://mcp.unitpost.com/mcp",
           "--header",
           "Authorization:${AUTH_HEADER}"
         ],
         "env": {
           "AUTH_HEADER": "Bearer pk_live_YOUR_KEY"
         }
       }
     }
   }

   Deliberately no space after Authorization: in args — Claude Desktop mangles spaces there; the value lives in env instead. Requires Node.js 18+. If npx is not found, set "command" to your absolute npx path (e.g. /opt/homebrew/opt/node@22/bin/npx). Save, then ⌘Q (Quit) Claude Desktop — closing the window is not enough.

5. 5

   Codex CLI (TOML)

   The CLI reads static config only. Edit `~/.codex/config.toml` (create it if needed).

   TOML

   [mcp_servers.unitpost]
   url = "https://mcp.unitpost.com/mcp"
   
   [mcp_servers.unitpost.http_headers]
   Authorization = "Bearer pk_live_YOUR_KEY"

6. 6

   VS Code (runtime-prompted key)

   Create or edit `.vscode/mcp.json`. When VS Code prompts later, paste only the pk_live_… value — not Bearer (the config already adds it).

   JSON

   {
     "inputs": [
       {
         "id": "unitpost-key",
         "type": "promptString",
         "description": "Unitpost API key (pk_live_…)",
         "password": true
       }
     ],
     "servers": {
       "unitpost": {
         "type": "http",
         "url": "https://mcp.unitpost.com/mcp",
         "headers": {
           "Authorization": "Bearer ${input:unitpost-key}"
         }
       }
     }
   }

7. 7

   Gemini CLI (static header)

   Edit `~/.gemini/settings.json` (user-level) or `.gemini/settings.json` (project).

   JSON

   {
     "mcpServers": {
       "unitpost": {
         "httpUrl": "https://mcp.unitpost.com/mcp",
         "headers": {
           "Authorization": "Bearer pk_live_YOUR_KEY"
         }
       }
     }
   }

8. 8

   Windsurf (static header)

   Edit `~/.codeium/windsurf/mcp_config.json`. Windsurf uses serverUrl (not url) for remote HTTP.

   JSON

   {
     "mcpServers": {
       "unitpost": {
         "serverUrl": "https://mcp.unitpost.com/mcp",
         "headers": {
           "Authorization": "Bearer pk_live_YOUR_KEY"
         }
       }
     }
   }

9. 9

   OpenCode (static header)

   Set oauth: false and pass the Bearer key.

   JSON

   {
     "mcp": {
       "unitpost": {
         "type": "remote",
         "url": "https://mcp.unitpost.com/mcp",
         "oauth": false,
         "headers": {
           "Authorization": "Bearer pk_live_YOUR_KEY"
         }
       }
     }
   }

10. 10

    Any other client (generic)

    Configure a streamable-HTTP MCP server with the URL below, and send the header on every MCP request.

    JSON

    {
      "url": "https://mcp.unitpost.com/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_KEY"
      }
    }

11. 11

    Verify with the key

    Call a read tool (e.g. list domains). A 401 Invalid API key usually means a missing Bearer prefix or a mistyped key — recreate the key and retry. Then send a test email from a verified domain and confirm it in Unitpost Activity.

    Don't see it? Fully quit and reopen the client — closing the window is often not enough — then check again.