Integration brevo

/integration-brevo — connect Brevo to a remote Hermes (SSH-first)

You are the engineer connecting Brevo to a self-hosted Hermes agent on the user's VPS. You (the AI agent — Hermes, Claude Code, Codex, Cursor, Gemini, any of them) work over SSH as root against the VPS. The user only does the two things a machine cannot:

1. Mint the MCP-enabled API key in the Brevo UI.
2. Validate the sender address or sending domain that campaigns will originate from.

Everything else — token storage, MCP registration, gateway reload, verification — runs on the VPS via SSH, idempotently.

Honest auth picture (verified 2026-06): Brevo ships an official first-party remote HTTP MCP server at https://mcp.brevo.com/v1/brevo/mcp that accepts a static bearer MCP token (no OAuth required). That is the headless-friendly path and the one this skill uses. A plain REST API key created without the MCP option will return 401 against the MCP endpoint — the key must be minted with the MCP checkbox enabled. See https://developers.brevo.com/docs/mcp-protocol.

---

Before you start — gather (ask once, in one batch)

Variable	What	Where to get it
$VPS_IP	IP/hostname of the VPS running Hermes	User's hosting dashboard
$VPS_USER	SSH user (typically root)	User's hosting dashboard
$BREVO_TOKEN	MCP-enabled API key	Brevo dashboard: Account → SMTP & API → API Keys → Generate a new API key, then check the MCP option before saving. Copy immediately; Brevo will not show it again.
Validated sender	At least one verified sender address or authenticated domain	Brevo: Senders, Domains & Dedicated IPs → Senders

Confirm SSH access before doing anything:

ssh -o StrictHostKeyChecking=accept-new -o BatchMode=yes \
    "$VPS_USER@$VPS_IP" "echo ok" 2>&1 | grep -q '^ok$' \
  || { echo "ABORT: SSH to $VPS_USER@$VPS_IP failed. Run /setup-ssh-keys first."; exit 1; }

---

Step 1 — verify Hermes is reachable on the VPS

ssh "$VPS_USER@$VPS_IP" '
  set -e
  if command -v hermes >/dev/null 2>&1; then
    hermes --version
  elif docker ps --format "{{.Names}}" | grep -q hermes; then
    AGENT=$(docker ps --filter name=hermes --format "{{.Names}}" | head -1)
    docker exec "$AGENT" hermes --version
  else
    echo "FAIL: hermes not found on host or in container"; exit 1
  fi
' || { echo "ABORT: Hermes is not installed/running. Run /hermes-install first."; exit 1; }

Expected: 0.15.x or 0.17.x.

---

Step 2 — idempotency check (skip if already wired)

ALREADY=$(ssh "$VPS_USER@$VPS_IP" "hermes mcp list 2>/dev/null | grep -ci brevo" || echo 0)
if [ "$ALREADY" -gt 0 ] && [ "${FORCE:-0}" != "1" ]; then
  echo "Brevo is already wired. Set FORCE=1 to rewire."
  exit 0
fi

---

Step 3 — DRY RUN preview (always show before writing)

cat <<EOF
DRY RUN — the following will happen on $VPS_USER@$VPS_IP:
  1. Write MCP_BREVO_API_KEY (length ${#BREVO_TOKEN}, prefix ${BREVO_TOKEN:0:4}...) via 'hermes config set'
  2. chmod 600 ~/.hermes/.env
  3. Register MCP: hermes mcp add brevo --url https://mcp.brevo.com/v1/brevo/mcp --auth header
  4. Reload gateway: hermes gateway stop && hermes gateway run
  5. Verify in logs: grep -i "registered.*brevo"
  6. Smoke test: POST https://mcp.brevo.com/v1/brevo/mcp initialize → expect 200

The token is NEVER printed in plaintext.
EOF

Wait for user confirmation (or skip if AUTO_APPROVE=1).

---

Step 4 — write the secret (chmod 600, no echo, no logging)

ssh "$VPS_USER@$VPS_IP" "hermes config set MCP_BREVO_API_KEY '$BREVO_TOKEN'"
ssh "$VPS_USER@$VPS_IP" "chmod 600 ~/.hermes/.env"

Verify (returns 1, NEVER the value):

WROTE=$(ssh "$VPS_USER@$VPS_IP" "grep -c '^MCP_BREVO_API_KEY=' ~/.hermes/.env" || echo 0)
[ "$WROTE" = "1" ] || { echo "FAIL: MCP_BREVO_API_KEY not written. Rolling back."; rollback; exit 1; }

If your Hermes build has no config set subcommand, use the safe sed pattern (pipe delimiter; Brevo MCP tokens are alnum but the pattern is safe for any token):

ssh "$VPS_USER@$VPS_IP" "
  grep -q '^MCP_BREVO_API_KEY=' ~/.hermes/.env || printf 'MCP_BREVO_API_KEY=\n' >> ~/.hermes/.env
  sed -i 's|^MCP_BREVO_API_KEY=.*|MCP_BREVO_API_KEY=$BREVO_TOKEN|' ~/.hermes/.env
  chmod 600 ~/.hermes/.env
"

---

Step 5 — register the Brevo MCP server

Pick the path that matches the Hermes build on the VPS. Path A is preferred.

Path A (preferred) — Brevo's first-party remote HTTP MCP

ssh "$VPS_USER@$VPS_IP" "
  hermes mcp add brevo \
    --url 'https://mcp.brevo.com/v1/brevo/mcp' \
    --auth-header 'Authorization' \
    --auth-scheme 'Bearer' \
    --auth-value '\${MCP_BREVO_API_KEY}'
"

The flag names vary by Hermes version. If unsure, run hermes mcp add --help first and match its HTTP-MCP syntax. The token stays in ~/.hermes/.env and is referenced via ${MCP_BREVO_API_KEY} indirection — never inlined into config.yaml.

If your Hermes build only supports placeholder-then-inject (older builds), use:

ssh "$VPS_USER@$VPS_IP" "
  printf 'y\nAuthorization\nplaceholder\n' | \
    hermes mcp add brevo --url 'https://mcp.brevo.com/v1/brevo/mcp' --auth header
"
# No sed-into-config.yaml — the token already lives in ~/.hermes/.env from Step 4.
# The placeholder will resolve from MCP_BREVO_API_KEY at gateway runtime.

Path B (fallback) — generic HTTP tool against the Brevo REST API

If the Hermes build is stdio-MCP-only or cannot reach mcp.brevo.com:

• Base URL: https://api.brevo.com/v3
• Auth header: api-key: ${MCP_BREVO_API_KEY} (NOT Authorization: Bearer — REST uses a different scheme than MCP)
• Content type: Content-Type: application/json
• Common endpoints: /account, /contacts, /emailCampaigns, /smtp/email

Do NOT mix the headers — Authorization: Bearer belongs on mcp.brevo.com, api-key: belongs on api.brevo.com. The same secret value works on both endpoints when the key was minted with the MCP option, but the header name differs.

---

Step 6 — reload the gateway (stop + run, NOT restart)

gateway restart does NOT reliably re-read .env. Always use stop + run.

ssh "$VPS_USER@$VPS_IP" "hermes gateway stop || true"
sleep 2
ssh "$VPS_USER@$VPS_IP" "hermes gateway run --daemon"
sleep 5

---

Step 7 — verify registration in logs (poll up to 30s)

REGISTERED=0
for i in $(seq 1 6); do
  if ssh "$VPS_USER@$VPS_IP" "hermes logs 2>&1 | tail -200" \
       | grep -qiE "registered.*tool.*brevo|MCP server.*brevo.*(ok|ready|registered)"; then
    REGISTERED=1
    echo "OK: brevo registered in gateway logs."
    break
  fi
  sleep 5
done
[ "$REGISTERED" = "1" ] || { echo "FAIL: brevo not in logs after 30s. Rolling back."; rollback; exit 1; }

---

Step 8 — live API smoke test (inside the container so the token stays on the VPS)

HTTP=$(ssh "$VPS_USER@$VPS_IP" "
  curl -sS -o /dev/null -w '%{http_code}' \
    -X POST 'https://mcp.brevo.com/v1/brevo/mcp' \
    -H 'Accept: application/json, text/event-stream' \
    -H 'Content-Type: application/json' \
    -H \"Authorization: Bearer \$MCP_BREVO_API_KEY\" \
    -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"verify\",\"version\":\"0\"}}}'
")
case "$HTTP" in
  200) echo "OK: Brevo MCP reachable and token valid." ;;
  401) echo "FAIL: token invalid or missing MCP option. Re-mint with MCP checkbox enabled."; rollback; exit 1 ;;
  403) echo "FAIL: token valid but scope/plan does not permit MCP."; exit 1 ;;
  *)   echo "WARN: unexpected HTTP $HTTP from Brevo MCP. Check manually." ;;
esac

A 200 from initialize proves the handshake works, but Brevo (like most servers) enforces auth on tools/call, not just initialize. For a stronger check, follow the session-id flow and call tools/list — a populated tools array is the real proof.

---

Rollback (auto-runs on any failure above)

rollback() {
  ssh "$VPS_USER@$VPS_IP" "hermes mcp remove brevo 2>/dev/null || true"
  ssh "$VPS_USER@$VPS_IP" "hermes config unset MCP_BREVO_API_KEY 2>/dev/null || \
    sed -i '/^MCP_BREVO_API_KEY=/d' ~/.hermes/.env"
  ssh "$VPS_USER@$VPS_IP" "hermes gateway stop; sleep 2; hermes gateway run --daemon"
  echo "Rolled back. Brevo is no longer wired."
}

---

Pitfalls

#	Pitfall	Why it bites	Prevention
1	Using a plain REST API key against mcp.brevo.com	Brevo keys must have the MCP option checked at creation; plain v3 keys return 401 on the MCP endpoint	Re-mint with the MCP checkbox enabled
2	Confusing the REST API header with the MCP header	REST uses api-key: <key> against https://api.brevo.com/v3; MCP uses Authorization: Bearer <token> against https://mcp.brevo.com/v1/brevo/mcp	Use bearer header only for the MCP path; api-key only for api.brevo.com
3	Sending campaigns from an unverified sender	Brevo rejects sends from non-validated senders, even with a valid token	Validate the sender / authenticate the domain in Brevo before first send
4	Treating initialize success as proof	Handshake is often open; auth is enforced on tools/call	Run a tools/list probe with Mcp-Session-Id to confirm
5	Rate limits	Brevo throttles per-account; bursts get 429	Backoff on 429; chunk contact imports
6	gateway restart to pick up env	Restart does NOT reliably re-read .env	Always stop + run
7	echo >> .env instead of config set	Can merge onto a prior line without trailing newline → key is silently invalid	Always hermes config set (or the safe sed pattern with pipe delimiter)
8	Token in config.yaml instead of .env	World-readable; not loaded by Hermes runtime	Only ~/.hermes/.env, chmod 600
9	sed with / delimiter on tokens	Brevo MCP tokens are alnum today, but future tokens may include /+=	Always use | delimiter
10	Container vs host confusion when running on the VPS	SSH-as-root lands on the host; hermes may live inside a docker container	Step 1 detects host vs container and dispatches docker exec automatically
11	Hermes not running when SSH connects	First call hangs forever	Step 1 has a hard version check that exits early

---

Definition of done

• SSH to $VPS_USER@$VPS_IP succeeded
• Hermes version verified on the VPS (0.15.x / 0.17.x)
• Idempotency check passed (or FORCE=1 overrode)
• Dry-run shown; user approved (or AUTO_APPROVE=1)
• MCP_BREVO_API_KEY in ~/.hermes/.env, chmod 600, not in config.yaml or chat
• Sender address or sending domain validated in the Brevo UI
• MCP registered via Path A (mcp.brevo.com) or REST documented via Path B
• Gateway reloaded with stop + run (NOT restart)
• Logs show registered N tool(s) for 'brevo' within 30s
• Smoke test: initialize POST to https://mcp.brevo.com/v1/brevo/mcp returned 200
• Rollback function defined and proven (re-run with FORCE=1 rewires cleanly)

See reference/TROUBLESHOOTING.md for gateway and MCP failure modes.