Headless / API key

What are the connection details?

How do I connect Headless / API key?

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.