Install the Courier MCP Server and CLI

Last updated: May 2026

The pieces

Courier's notification infrastructure ships two programmatic surfaces for managing it outside the dashboard:

• The MCP server at mcp.courier.com, for AI tools to read and write your Courier account from inside a prompt.
• The CLI (@trycourier/cli), for terminals, scripts, and CI to do the same operations from the command line.

Both read the same Courier API and authenticate with the same API key from your workspace. The MCP server is a remote HTTP MCP endpoint, so there's nothing to install on your machine for it; you add the URL to your AI tool's MCP config and pass the key as an api_key header. The CLI is an npm package you install once and authenticate by exporting COURIER_API_KEY in your shell.

Most teams install both. The MCP server is what your AI tool uses day to day. The CLI is what you reach for in CI/CD, in setup scripts, or when you want a deterministic action without going through an LLM. There's a real debate about when each is the right tool, covered in Your AI agent already knows how to use a terminal. Why CLIs beat MCP servers and Terminal-First Development vs. IDE: Building Notification Infrastructure.

Before either, you need:

1. A Courier account. Free tier is fine. Sign up at courier.com. See current plan limits for what fits your volume.
2. An API key. Generated from Settings → API Keys in the Courier dashboard. The same key works for the CLI, the MCP server, the REST API, and every Courier SDK. Note that Courier exposes a Test and a Production environment, each with its own key; use the Test key while you're wiring things up and switch to Production when you're ready for real traffic.

Both install in a couple of minutes. Start with whichever path matches what you'll do first.

Installing the Courier MCP server

The MCP server is a remote HTTP endpoint at https://mcp.courier.com. Every MCP-capable client connects the same way: add the URL, pass your Courier API key as an api_key header, and the 109 Courier tools become available the next time your tool refreshes its tool list. There is no OAuth flow; the same API key you'd use against the REST API is the one the MCP server reads.

The install snippet your client needs:

• Claude Code uses one command: claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY. That writes the entry into your Claude Code MCP config and the tools show up in your next prompt.
• Cursor edits its config under Cursor Settings → Tools & Integrations → MCP Tools → New MCP Server. The entry is a small JSON block with the server url set to https://mcp.courier.com and a headers object containing api_key.
• Windsurf uses Windsurf Settings → Manage MCP Servers → View Raw Config. Same shape as Cursor (server URL plus an api_key header), under the mcpServers key.
• Claude Desktop doesn't speak remote HTTP MCP natively, so it goes through a stdio shim: in Claude → Settings → Developer → Edit Config, add a server entry that runs npx -y mcp-remote https://mcp.courier.com --header "api_key: YOUR_COURIER_API_KEY".
• VS Code uses a workspace file at .vscode/mcp.json with the server URL, type: "http", and the api_key header.
• OpenAI's Responses API accepts the MCP server as a tool configuration with type: "mcp", the server URL, and the API key in headers.

Whichever client you're on, the MCP docs page has the exact config block to copy in. For the underlying implementation see The Courier MCP Server Is Open Source. Here's How It Actually Works.

A scope note worth knowing up front: connecting channel providers (Gmail OAuth, Twilio API key, Slack bot token, and so on) happens in the Courier dashboard, not through MCP. Once a provider is connected, every send the agent dispatches runs through it. Provider management surfaces in the API mostly handle reading configuration and routing rules, not first-time provider OAuth.

Installing the Courier CLI

The CLI is published as @trycourier/cli on npm. A global install (npm install -g @trycourier/cli) is the usual choice; npx @trycourier/cli works for ad-hoc invocations without a global install.

The CLI reads COURIER_API_KEY from your environment. Export it in your shell profile and every subcommand picks it up automatically. There is no separate courier auth or courier login command; the env var is the auth model. The --api-key flag overrides it for one-off calls, which is the right pattern when you bounce between Test and Production keys.

The CLI exposes Courier's REST surface as resource groups: send, messages, notifications, profiles, lists, bulk, tenants, user-tenants, automations, preferences, plus journeys, providers, brands, routing-strategies, translations, and audiences. The two you'll reach for first are courier send message (to dispatch a message) and courier messages list (to inspect deliveries). The send command takes the message body as flat dotted flags: --message.to.email, --message.content.title, --message.content.body, --message.template, --message.data, and so on, which is the same shape the REST API accepts under its message key. For CI use, set COURIER_API_KEY as a secret and shell out to courier directly; the exit code is non-zero on failure, and --format json (or jsonl, yaml, raw) makes the output pipeable. Full reference at the CLI docs.

As of CLI 3.4.2, the courier journeys resource ships list and invoke only. The create, replace, publish, and journey-scoped template operations don't have CLI commands yet; for those, use a Courier SDK or hit the REST endpoints directly. The /courier-journeys-create skill (covered next) falls back to SDKs automatically when it needs operations the CLI doesn't ship.

Installing Courier skills

A skill is a packaged set of instructions your AI tool reads when a relevant prompt comes in. The skill format is a SKILL.md markdown file with a small YAML header (name, description, trigger phrases) plus task-specific resource files the skill references. The tool loads the skill when the user's prompt matches and follows the routing inside.

Courier publishes the whole skill bundle in one repository, trycourier/courier-skills, which you clone into your harness's skills directory:

• Claude Code discovers skills under ~/.claude/skills/. Clone into ~/.claude/skills/courier-skills.
• Cursor (global) uses ~/.cursor/skills/. Clone into ~/.cursor/skills/courier-skills.
• Cursor (project-scoped) reads .cursor/skills/ next to the project. Clone into .cursor/skills/courier-skills inside the repo.
• Windsurf, Cline, and other agents follow the same pattern: clone into whatever skills directory the tool supports.

There is no one-shot plugin install command (claude plugins add courier is not a real command). Clone the repo, point your tool at it, and the skills become available next session.

The /courier-journeys-create skill, the /courier-template-create skill, and the courier-writing-guide come bundled, alongside reference files for the seven channels (email, SMS, push, in-app inbox, Slack, Microsoft Teams, WhatsApp), five transactional notification types, six growth flows, and ten cross-cutting topics like multi-channel routing, preferences, compliance, and reliability. Skills are scoped: they only activate when the prompt matches, so you can install the whole bundle and the right skill loads per prompt. See Introducing Courier Skills for the why-and-how on the skill format. Chapter 5 covers the broader pattern of giving an autonomous agent messaging tools, including the safety guardrails to set up before letting it send without review.

"The first comment I received from a developer when they first started to use Courier was how easy it was to create a new notification."

Marc-André, Officevibe (the team replaced an in-house notification system with Courier so they could focus on product instead of infrastructure)

Connecting your first channel provider

A channel provider is the actual sender for a channel: Gmail or SendGrid for email, Twilio for SMS, FCM or APNS for push, Slack for chat. Provider setup happens in the Courier dashboard under Channels. The first one is the easiest, and Gmail is the easiest first one because the dashboard walks you through OAuth in the browser, stores the credentials, and registers it as an available email provider with no API key to manage. See the Gmail provider docs for what gets stored.

For providers that use an API key (SendGrid, Twilio, Postmark, Slack bot tokens, FCM service accounts), paste the credential into the dashboard's provider page and save. Courier stores it server-side; your agent never sees it, and your application code never has to handle it. Once a provider is connected, every send call routes through it automatically based on the notification's routing config.

If you'd rather list providers from the terminal, courier providers list returns the configured set, and courier providers:catalog lists every provider Courier supports. Provider creation itself, though, lives in the dashboard.

Verifying the install: your first send

Test the install by sending a real message. Through the agent: "Send a test email to alex@example.com that says 'Courier is connected.'" From the CLI:

courier send message \
  --message.to.email "alex@example.com" \
  --message.content.title "Courier is connected" \
  --message.content.body "Hello from the CLI."

Either way you'll get a requestId back and the message arrives in a few seconds. If it doesn't, fetch the log with courier messages list --recipient alex@example.com and drill into a specific message with courier messages retrieve --message-id . The log includes provider response codes and any channel errors. Chapter 3 covers designing real templates instead of inline content, plus the production patterns (user_id recipients, idempotency keys, webhook handling) the agent quickstart recommends once you're past the test send.

FAQs

What does the MCP install actually do?

It registers a remote HTTP endpoint with your AI tool and tells it to pass your Courier API key as an api_key header on every call. The endpoint exposes Courier's API as a set of typed tools (send_message, create_notification, invoke_journey, and so on). When your agent decides it needs to do something Courier-related, it picks the right tool and calls it. The agent never has to read Courier's REST docs because the tool definitions include parameter schemas and descriptions.

Do I need an API key to start?

Yes for both. The MCP server reads the API key from the api_key header your client passes; the CLI reads it from COURIER_API_KEY. Generate the key from the Courier dashboard under Settings → API Keys. Test and Production environments each have their own key.

Do I need both the MCP server and the CLI?

No, but most teams install both. The MCP server is the AI-tool surface. The CLI is the terminal and CI/CD surface. They share the same underlying API, so anything you do in one is visible in the other (a template created through the agent shows up in courier notifications list).

Can a teammate share my MCP setup?

The MCP server URL is the same for everyone. Each teammate adds the same mcp.courier.com URL to their AI tool's config and supplies their own Courier API key. The key determines which workspace they reach; if you're sharing a workspace, you each generate a key from your own user and the server scopes calls accordingly.

What's the difference between the MCP server and a skill?

The MCP server is the API surface. It exposes tools the agent can call. A skill is a prompt-time instruction that tells the agent how to use those tools for a specific task. The MCP server is required. Skills are optional but make common tasks more reliable.

Which AI coding tools does Courier work with?

Any tool that supports MCP. Today that includes Claude Code, Cursor, Windsurf, the Claude Desktop app, VS Code, and OpenAI's Responses API. As new MCP-compatible tools ship, Courier works with them automatically since the protocol is standardized. See the AI onboarding guide for a tool-by-tool walkthrough and a machine-readable docs index at courier.com/docs/llms.txt that an agent can fetch on its own.

Ready to put this into production? See pricing or talk to our solutions team.