> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message`, the default import of the v7 Node SDK. Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Courier MCP server

> Connect an AI agent to the hosted MCP server at mcp.courier.com to use the Courier API as tools.

export const AppLink = ({href, children, name, bare}) => {
  const label = children || name || "Open in Courier";
  if (bare) {
    return <a href={href} target="_blank" rel="noreferrer">{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="app" href={href} target="_blank" rel="noreferrer">
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method" aria-hidden="true">↗</span>
    </a>;
};

export const Doc = ({href, children, name, bare}) => {
  const label = children || name || href;
  if (bare) {
    return <a href={href}>{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="doc" href={href}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">DOC</span>
    </a>;
};

The hosted MCP server at `https://mcp.courier.com` exposes the <Doc href="/docs/reference/api-overview">Courier REST API</Doc> as typed tools. Your agent discovers them automatically.

Authenticate with an API key from <AppLink href="https://app.courier.com/settings/api-keys">Settings → API Keys</AppLink>. Each client takes the key as a header, flag, or config field.

## Installation

<Tabs>
  <Tab title="Claude Code">
    Run:

    ```bash theme={null}
    claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY
    ```

    <Tip>
      This registers the server for the current project. Add `--scope user` to register it in every project.
    </Tip>
  </Tab>

  <Tab title="Cursor">
    **Quick install**

    <a href="https://cursor.com/en/install-mcp?name=courier&config=eyJ1cmwiOiJodHRwczovL21jcC5jb3VyaWVyLmNvbSIsImhlYWRlcnMiOnsiYXBpX2tleSI6IllPVVJfQ09VUklFUl9BUElfS0VZIn19" target="_blank">
      <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add to Cursor" height="32" style={{maxWidth: '200px'}} className="block dark:hidden" noZoom />

      <img src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Add to Cursor" height="32" style={{maxWidth: '200px'}} className="hidden dark:block" noZoom />
    </a>

    **Manual install**

    In Cursor, go to **Cursor > Cursor Settings > Tools & Integrations > MCP Tools > New MCP Server** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "courier": {
          "url": "https://mcp.courier.com",
          "headers": {
            "api_key": "YOUR_COURIER_API_KEY"
          }
        }
      }
    }
    ```

    <Tip>
      Courier MCP works best with Agent mode enabled.
    </Tip>
  </Tab>

  <Tab title="Codex">
    Add this to `~/.codex/config.toml` (create the file if it doesn't exist), then restart Codex:

    ```toml theme={null}
    [mcp_servers.courier]
    url = "https://mcp.courier.com"
    http_headers = { "api_key" = "YOUR_COURIER_API_KEY" }
    ```

    <Tip>
      The Codex CLI and the Codex IDE extension share this config file, so one entry covers both. `codex mcp add` doesn't support custom headers, so edit the file directly.
    </Tip>
  </Tab>

  <Tab title="Antigravity">
    Antigravity's IDE, CLI, and Agent Manager share one MCP config. Add this to `~/.gemini/config/mcp_config.json` (create the file if it doesn't exist):

    ```json theme={null}
    {
      "mcpServers": {
        "courier": {
          "serverUrl": "https://mcp.courier.com",
          "headers": {
            "api_key": "YOUR_COURIER_API_KEY"
          }
        }
      }
    }
    ```

    Then refresh the server list:

    * In the Antigravity IDE, go to **Settings > Customizations > Installed MCP Servers** and click **Refresh**.
    * In the Antigravity CLI, run `/mcp` to confirm the courier server is connected.

    <Tip>
      Antigravity requires `serverUrl` for remote servers. It doesn't support the `url` or `httpUrl` fields other clients use.
    </Tip>
  </Tab>

  <Tab title="VS Code">
    Create `.vscode/mcp.json` in your project and add:

    ```json theme={null}
    {
      "inputs": [
        {
          "type": "promptString",
          "id": "courier-api-key",
          "description": "API key for Courier service",
          "password": true
        }
      ],
      "servers": {
        "courier": {
          "url": "https://mcp.courier.com",
          "type": "http",
          "headers": {
            "api_key": "${input:courier-api-key}"
          }
        }
      }
    }
    ```

    Open the chat window, click the Gear icon, then **MCP Servers**, and start the "courier" server.

    <Tip>
      VS Code works best when you prefix chat prompts with `#`. For example: `#get_user_profile_by_id example_user_id`.
    </Tip>
  </Tab>

  <Tab title="Windsurf">
    Add the following to `~/.codeium/windsurf/mcp_config.json` (create the file if it doesn't exist):

    ```json theme={null}
    {
      "mcpServers": {
        "courier": {
          "serverUrl": "https://mcp.courier.com",
          "headers": {
            "api_key": "YOUR_COURIER_API_KEY"
          }
        }
      }
    }
    ```

    <Tip>
      Windsurf uses `serverUrl` for remote servers, not `url`.
    </Tip>
  </Tab>

  <Tab title="Gemini CLI">
    Add the following to `~/.gemini/settings.json` for every project, or `.gemini/settings.json` for one project:

    ```json theme={null}
    {
      "mcpServers": {
        "courier": {
          "httpUrl": "https://mcp.courier.com",
          "headers": {
            "api_key": "YOUR_COURIER_API_KEY"
          }
        }
      }
    }
    ```

    <Tip>
      Use `httpUrl`, which selects the streamable HTTP transport the Courier server speaks. `url` selects SSE instead. Paste the key itself: Gemini CLI does not expand environment variables inside `headers`.
    </Tip>
  </Tab>

  <Tab title="Grok Build">
    In a terminal, run:

    ```bash theme={null}
    grok mcp add --transport http courier https://mcp.courier.com --header "api_key: YOUR_COURIER_API_KEY"
    ```

    Or add the server to `~/.grok/config.toml` directly:

    ```toml theme={null}
    [mcp_servers.courier]
    url = "https://mcp.courier.com"
    headers = { "api_key" = "YOUR_COURIER_API_KEY" }
    ```

    <Tip>
      Pass `--scope project` to store the server in `.grok/config.toml` inside the repository instead. `grok mcp list` shows configured servers and `grok mcp doctor courier` checks connectivity.
    </Tip>
  </Tab>

  <Tab title="OpenCode">
    Add the following to `opencode.json` in your project:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "courier": {
          "type": "remote",
          "url": "https://mcp.courier.com",
          "enabled": true,
          "headers": {
            "api_key": "{env:COURIER_API_KEY}"
          }
        }
      }
    }
    ```

    <Tip>
      `{env:COURIER_API_KEY}` reads the key from your environment so it never lands in the file. Replace it with the key itself if you prefer.
    </Tip>
  </Tab>

  <Tab title="Zed">
    Open your settings file (`zed: open settings file` from the command palette) and add:

    ```json theme={null}
    {
      "context_servers": {
        "courier": {
          "url": "https://mcp.courier.com",
          "headers": {
            "api_key": "YOUR_COURIER_API_KEY"
          }
        }
      }
    }
    ```

    <Tip>
      Zed calls MCP servers context servers. Remote servers take `url` and `headers`; leave `command` out.
    </Tip>
  </Tab>

  <Tab title="Warp">
    In Warp, go to **Settings > Agents > MCP servers**, click **+ Add**, and paste:

    ```json theme={null}
    {
      "courier": {
        "url": "https://mcp.courier.com",
        "headers": {
          "api_key": "YOUR_COURIER_API_KEY"
        }
      }
    }
    ```

    <Tip>
      Warp supports the streamable HTTP transport the Courier server uses. The top-level key is the server name.
    </Tip>
  </Tab>

  <Tab title="Devin">
    In the Devin web app, go to **Customize > MCPs** and click **Add custom MCP**. Fill in:

    * **Transport:** HTTP
    * **URL:** `https://mcp.courier.com`
    * **Auth method:** Auth Header
    * **Header name:** `api_key`
    * **Header value:** your Courier API key

    <Tip>
      MCP servers in Devin are configured for the whole organization, so every member shares this connection. Use a dedicated API key for it rather than a personal one.
    </Tip>
  </Tab>

  <Tab title="Claude Desktop">
    In Claude Desktop, go to **Claude > Settings > Developer > Edit Config**, then add:

    ```json theme={null}
    {
      "mcpServers": {
        "courier": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.courier.com", "--header", "api_key: YOUR_COURIER_API_KEY"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What it covers

<Doc href="/docs/resources/mcp/tools">Tools</Doc> lists every tool the server exposes, by resource, and marks which ones write.
161 tools across the API surface:

| Area               | What the agent can do                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------- |
| Send               | Send to a user, List, or Template, and cancel or resend a message                            |
| Messages           | List, retrieve, read history, content, and delivery status, and trace a delivery in one call |
| Users              | Create, merge, replace, and patch Profiles, and manage push tokens                           |
| Lists & Audiences  | Create Lists, subscribe and unsubscribe users, query Audience members                        |
| Templates          | Create, publish, archive, and read or replace content, elements, and locales                 |
| Journeys           | Create, publish, invoke, cancel, and version Journeys and their Templates, and read run logs |
| Preferences        | Read and write Topics, Sections, digests, and per-user and per-tenant preferences            |
| Broadcasts         | Create, schedule, and send a Broadcast to a List or Audience                                 |
| Tenants            | Create Tenants, manage membership, and set Tenant Templates and preferences                  |
| Brands & Providers | Create and update Brands, Providers, and Routing Strategies                                  |
| Automations        | Invoke a Template or ad-hoc Automation, and cancel a run                                     |
| Analytics          | Read audit events, digest instances, and the provider catalog                                |

Ask your agent to list its Courier tools for the current set. The <Doc href="/docs/reference/api-overview">API reference</Doc> documents the endpoints behind them.