marginal documentation

Last updated: June 24, 2026 · Hosted email marketing MCP server

marginal is a hosted MCP server for AI agents. It exposes four tools to write subject lines, send email split tests, measure opens and clicks, and recommend the next campaign angle — without Mailchimp, Klaviyo, or a separate ESP integration.

Connect (Cursor, Codex, or Claude Desktop)

Create a free account at marginal.sh/signup.
Open the dashboard and create an API key.
Add marginal as a remote MCP server (see client-specific config below).

Cursor and Claude Desktop

Add to your MCP config (e.g. Cursor settings or Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "marginal": {
      "url": "https://marginal.sh/mcp",
      "headers": {
        "Authorization": "Bearer marg_live_..."
      }
    }
  }
}

OpenAI Codex

Codex uses Streamable HTTP MCP servers in ~/.codex/config.toml (or project-scoped .codex/config.toml). Put your API key in an environment variable — do not paste the secret into the config file.

export MARGINAL_API_KEY=marg_live_...

# Option A: CLI helper
codex mcp add marginal \
  --url https://marginal.sh/mcp \
  --bearer-token-env-var MARGINAL_API_KEY

# Option B: edit ~/.codex/config.toml
[mcp_servers.marginal]
url = "https://marginal.sh/mcp"
bearer_token_env_var = "MARGINAL_API_KEY"
enabled = true

Start Codex from a shell where MARGINAL_API_KEY is exported, then run /mcp in a session to confirm the server loaded. See the Codex MCP docs for IDE extension setup.

Only your marginal API key is required. Delivery, tracking, and storage are managed on marginal.sh.

MCP tools

Each tool has a dedicated reference page with examples for agents and SEO/AEO discoverability.

Tool	What it does	Docs
`generate_variants`	Write subject line options from a brief, seed texts, or exact lines your agent already drafted.	Reference
`launch_test`	Randomly split recipients across variants, send the campaign, and start open/click tracking.	Reference
`get_results`	Return per-variant opens, clicks, winner, and within-test lift for an experiment.	Reference
`recommend_next`	Suggest which messaging dimension to test next based on prior results.	Reference

Agent workflow (end to end)

An AI agent in Cursor, Codex, or Claude Desktop can run a closed-loop email marketing experiment without ESP APIs. Typical sequence:

Write — call generate_variants with a brief or your subject lines
Send — call launch_test with variants + recipient list; save experiment_id
Wait — allow time for opens and clicks (minutes to hours depending on list size)
Measure — call get_results with the experiment id
Improve — call recommend_next, then start the next test

MCP tool calls (conceptual)

generate_variants({ brief: { goal: "cart recovery" }, count: 3 })
→ launch_test({ variants, recipients, winner_criteria: "clicks", destination_url })
→ get_results({ experiment_id })
→ recommend_next({ experiment_id })

CLI equivalent

# 1. Generate variants
marginal generate-variants --json '{
  "brief": {
    "product": "Running shoes",
    "audience": "Cart abandoners",
    "goal": "Recover checkout"
  },
  "count": 3
}'

# 2. Launch test (save experiment_id from response)
marginal launch-test --json '{
  "variants": [
    { "variant_text": "Your cart is waiting" },
    { "variant_text": "Still thinking about it?" }
  ],
  "recipients": [{ "email": "[email protected]" }],
  "winner_criteria": "clicks",
  "destination_url": "https://yourstore.com/cart"
}'

# 3. After engagement accumulates
marginal get-results --experiment-id "<id>"
marginal recommend-next --experiment-id "<id>"

CLI (optional)

The marginal-cli npm package is a thin client for the same hosted https://marginal.sh/mcp endpoint:

export MARGINAL_API_KEY=marg_live_...
npx marginal-cli generate-variants --json '{"source_variants":["Line A","Line B"]}'

Free tier limits

100 experiments per month
250,000 recipients per month
50,000 recipients per experiment
10 active API keys

MCP Registry

marginal is listed in the official MCP Registry as sh.marginal/mcp with remote URL https://marginal.sh/mcp.

Support

Questions: [email protected] · Privacy policy · FAQ