Articles on: Integrations

Connect SuperSend MCP to Codex

Connect SuperSend MCP to Codex


Purpose


This article walks through connecting SuperSend's MCP (Model Context Protocol) server to OpenAI Codex CLI. Once connected, you can ask the Codex agent to manage your SuperSend campaigns, contacts, senders, and deliverability directly from your terminal.


Prerequisites


  • A SuperSend account with at least one team.
  • A SuperSend API key (see How to get your API key below).
  • OpenAI Codex CLI installed and authenticated with your OpenAI account.


How to Get Your SuperSend API Key


Your organization already has an API key in SuperSend. You do not create or rotate it—it stays the same for your account. Copy it whenever you connect a new tool.


  1. Log in to SuperSend and go to Admin → System tab.
  2. In the IDs section, find the API Key field (next to Org ID).
  3. Click Copy to copy the key to your clipboard. Use it wherever the steps below say YOUR-API-KEY.


If you do not see Admin or the API Key field, you may need org admin access—ask a workspace admin.



Shortcut: Let Codex Set Itself Up


If you already have Codex open, you can skip the manual steps below. The Codex agent can read SuperSend's setup docs and configure the connection for you.


  1. Open a Codex session in your terminal.
  2. Paste the following URL and prompt:


> Read the setup docs at https://docs.supersend.io/docs/mcp-server and configure the SuperSend MCP server for me.


Codex will fetch the page, identify the correct setup command for Codex, and run it — or walk you through the exact steps.


You'll still need your SuperSend API key ready (see How to Get Your SuperSend API Key above). The manual steps below are here if you prefer to do it yourself or need to troubleshoot.



Steps


Step 1: Add the SuperSend MCP server


In your terminal, run the following command, replacing YOUR-API-KEY with your SuperSend API key:


codex mcp add supersend --url https://mcp.supersend.io/mcp --header "Authorization: Bearer YOUR-API-KEY"


This registers the SuperSend MCP server with your Codex configuration.


Step 2: Verify the connection


Start a Codex session and type:


List my SuperSend teams


The agent will call the list_teams tool and return your team names. If you see them, you're connected.



Manual Configuration (Alternative)


If you prefer to configure Codex manually, you can add the SuperSend server directly to your Codex MCP config file. Open ~/.codex/config.json (or the equivalent config file for your Codex installation) and add:


{
  "mcpServers": {
    "supersend": {
      "url": "https://mcp.supersend.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-API-KEY"
      }
    }
  }
}


Replace YOUR-API-KEY with your SuperSend API key. If the file already has other servers configured, add the "supersend" block inside the existing "mcpServers" object.



What You Can Do Once Connected


Here are some example prompts to use in a Codex session:


  • List my SuperSend campaigns — see all active and inactive campaigns
  • Add john@example.com to my "Q4 Outreach" campaign — enroll a contact
  • Why is my reply rate so low? — runs a deliverability diagnosis
  • When will my campaigns finish? Do I have enough capacity? — capacity forecast
  • Which senders are at risk? — per-sender health and bounce analysis
  • Show me the sequence for my "Product Launch" campaign — view campaign steps


If the agent asks for a Team ID or Campaign ID, just say "List my SuperSend teams first" and it will fetch the IDs automatically.



Expected Result


After setup, the Codex agent has access to SuperSend tools covering contacts, campaigns, senders, conversations, deliverability intelligence, domain health, and more. The tools are called automatically when you ask about SuperSend.


Troubleshooting


  • Issue: Codex says the SuperSend server is not found or not configured.

Fix: Re-run the codex mcp add command and confirm it completes without errors. Then restart your Codex session.


  • Issue: Authentication error or "Unauthorized" response from SuperSend.

Fix: Copy the key again from Admin → System → API Key → Copy and re-run the codex mcp add command (or update your manual config). Ensure the key was pasted in full with no extra spaces or line breaks.


  • Issue: The server is configured but tools don't respond.

Fix: Confirm the MCP endpoint is reachable by running curl https://mcp.supersend.io/health in your terminal. It should return {"status":"ok"}. A network or firewall issue may be blocking the connection.


  • Issue: Unsure where the Codex config file is located.

Fix: Run codex --help or check the Codex CLI documentation for the config file path on your operating system.




Updated on: 07/04/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!