Prerequisite: Create an API Key
You need a Courier API key to authenticate MCP requests. Create one in your Courier Settings, then replaceYOUR_COURIER_API_KEY in the installation config below.
Each MCP client passes the key differently (header, flag, or config field), but the value is the same API key you’d use with the REST API or any Courier SDK.
Installation
- Claude Code
- Cursor
- Codex
- Antigravity
- VS Code
- Claude Desktop
In a terminal, run:
claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY
This registers the server for the current project. Add
--scope user to make it available in every project.Quick install:
Manual install:
In Cursor, go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools > New MCP Server, then add:{
"mcpServers": {
"courier": {
"url": "https://mcp.courier.com",
"headers": {
"api_key": "YOUR_COURIER_API_KEY"
}
}
}
}
Courier MCP works best with Agent mode enabled.
Add the following to
~/.codex/config.toml (create the file if it doesn’t exist), then restart Codex:[mcp_servers.courier]
url = "https://mcp.courier.com"
http_headers = { "api_key" = "YOUR_COURIER_API_KEY" }
This configures both the Codex CLI and the Codex IDE extension — they share the same config file. The
codex mcp add command doesn’t support custom headers, so edit the config file directly.Antigravity’s IDE, CLI, and Agent Manager share one MCP config. Add the following to Then refresh the server list: in the Antigravity IDE, go to Settings > Customizations > Installed MCP Servers and click Refresh. In the Antigravity CLI, run
~/.gemini/config/mcp_config.json (create the file if it doesn’t exist):{
"mcpServers": {
"courier": {
"serverUrl": "https://mcp.courier.com",
"headers": {
"api_key": "YOUR_COURIER_API_KEY"
}
}
}
}
/mcp to confirm the courier server is connected.Antigravity requires
serverUrl for remote servers — the url and httpUrl fields used by other clients aren’t supported.Create Open the chat window, click the Gear icon, then MCP Servers, and start the “courier” server.
.vscode/mcp.json in your project and add:{
"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}"
}
}
}
}
VS Code works best when prefixing prompts with
# in the chat. For example: #get_user_profile_by_id example_user_id.In Claude Desktop, go to Claude > Settings > Developer > Edit Config, then add:
{
"mcpServers": {
"courier": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.courier.com", "--header", "api_key: YOUR_COURIER_API_KEY"]
}
}
}
Available Tools
The Courier MCP server exposes 145 tools covering the full Courier API surface: 144 default tools plus 1 diagnostic tool available in local installs. All tools are backed by the official@trycourier/courier Node SDK with typed error handling.
Send
| Tool | Description |
|---|---|
send_message | Send a message using inline title and body content |
send_message_template | Send a message using a notification template |
send_message_to_list | Send inline content to all subscribers of a list |
send_message_to_list_template | Send a template to all subscribers of a list |
Messages
| Tool | Description |
|---|---|
list_messages | List sent messages with filters (status, recipient, provider, tags) |
get_message | Get full details and delivery status of a message |
get_message_content | Get the rendered HTML, text, and subject of a sent message |
get_message_history | Get the event history for a message (enqueued, sent, delivered, etc.) |
cancel_message | Cancel a message currently being delivered |
resend_message | Resend a previously sent message to the same recipient as a new send |
Profiles
| Tool | Description |
|---|---|
get_user_profile_by_id | Get a user profile by ID |
create_or_merge_user | Create or merge values into an existing profile |
replace_profile | Fully replace a user profile (PUT) |
patch_profile | Partially update specific fields on a profile |
delete_profile | Delete a user profile |
get_user_list_subscriptions | Get all list subscriptions for a user |
subscribe_user_to_lists | Subscribe a user to one or more lists |
delete_user_list_subscriptions | Remove all list subscriptions for a user |
Lists
| Tool | Description |
|---|---|
list_lists | Get all lists, optionally filtered by pattern |
get_list | Get a list by ID |
get_list_subscribers | Get all subscribers of a list |
create_list | Create or update a list |
delete_list | Delete a list |
restore_list | Restore a previously deleted list |
subscribe_user_to_list | Subscribe a user to a list |
unsubscribe_user_from_list | Unsubscribe a user from a list |
bulk_subscribe_to_list | Subscribe multiple users to a list in one call |
add_subscribers_to_list | Add subscribers to a list |
Audiences
| Tool | Description |
|---|---|
get_audience | Get an audience by ID |
list_audiences | List all audiences |
list_audience_members | List members of an audience |
update_audience | Create or update an audience with a filter definition |
delete_audience | Delete an audience |
Notifications
| Tool | Description |
|---|---|
list_notifications | List notification templates |
get_notification | Get a notification template by ID |
get_notification_content | Get published content blocks of a template |
get_notification_draft_content | Get draft content blocks of a template |
create_notification | Create a new notification template |
replace_notification | Replace an existing notification template |
archive_notification | Archive a notification template |
publish_notification | Publish a draft notification template |
list_notification_versions | List version history of a template |
list_notification_checks | List checks (conditions) on a template |
update_notification_checks | Update checks (conditions) on a template |
put_notification_content | Replace the content of a notification template |
put_notification_element | Replace a specific element in a template |
put_notification_locale | Set locale-specific content for a template |
cancel_notification_submission | Cancel a pending notification submission |
create_notification → put_notification_content → create_routing_strategy → publish_notification → send_message. Pass "state": "PUBLISHED" on create_notification to skip steps 2–4 for simple templates. See Manage Templates via API for a full walkthrough.
Templates are created in
DRAFT state by default. Sending with a template ID that has never been published returns an error. Always call publish_notification before sending.Brands
| Tool | Description |
|---|---|
create_brand | Create a new brand |
get_brand | Get a brand by ID |
list_brands | List all brands |
update_brand | Update an existing brand |
delete_brand | Delete a brand |
Auth
| Tool | Description |
|---|---|
generate_jwt_for_user | Generate a JWT token for client-side SDK auth |
Device Tokens
| Tool | Description |
|---|---|
list_user_push_tokens | List all push/device tokens for a user |
get_user_push_token | Get a specific push token |
create_or_replace_user_push_token | Create or replace a push token |
bulk_add_user_tokens | Add multiple device tokens for a user |
patch_user_token | Partially update a device token |
delete_user_token | Delete a device token |
Automations
| Tool | Description |
|---|---|
invoke_automation_template | Invoke an automation from a template |
invoke_ad_hoc_automation | Invoke an ad-hoc automation with inline steps |
list_automations | List all automation templates |
cancel_automation | Cancel a running automation by its cancelation token |
Bulk
| Tool | Description |
|---|---|
create_bulk_job | Create a bulk job for multi-recipient sends |
add_bulk_users | Add users to an existing bulk job |
run_bulk_job | Trigger delivery for a bulk job |
get_bulk_job | Get the status of a bulk job |
list_bulk_users | List users in a bulk job |
Tenants
| Tool | Description |
|---|---|
get_tenant | Get a tenant by ID |
create_or_update_tenant | Create or replace a tenant |
list_tenants | List all tenants |
delete_tenant | Delete a tenant |
list_tenant_users | List all users in a tenant |
update_tenant_preference | Set default notification preferences for a tenant |
delete_tenant_preference | Remove default preferences for a tenant |
list_tenant_templates | List notification templates assigned to a tenant |
get_tenant_template | Get a specific tenant template override |
replace_tenant_template | Replace a tenant template override |
publish_tenant_template | Publish a tenant template override |
get_tenant_template_version | Get a specific version of a tenant template |
delete_tenant_template | Delete a tenant notification template |
Users
| Tool | Description |
|---|---|
get_user_preferences | Get a user’s notification preferences |
get_user_preference_topic | Get a user’s preference for a specific topic |
update_user_preference_topic | Update a user’s preference for a subscription topic |
delete_user_preference_topic | Reset a user’s preference for a topic back to its default |
bulk_update_user_preferences | Additively update a user’s preferences for multiple topics at once |
bulk_replace_user_preferences | Replace a user’s entire set of preference overrides in one request |
list_user_tenants | List all tenants a user belongs to |
add_user_to_tenant | Add a user to a tenant |
remove_user_from_tenant | Remove a user from a tenant |
bulk_add_user_tenants | Add a user to multiple tenants in one call |
remove_all_user_tenants | Remove a user from all tenants |
Routing Strategies
| Tool | Description |
|---|---|
create_routing_strategy | Create a reusable routing strategy |
get_routing_strategy | Get a routing strategy by ID |
replace_routing_strategy | Replace a routing strategy |
archive_routing_strategy | Archive a routing strategy |
list_routing_strategies | List all routing strategies |
list_routing_strategy_notifications | List notifications using a routing strategy |
Journeys
| Tool | Description |
|---|---|
list_journeys | List all journeys |
invoke_journey | Invoke a journey run for a user |
create_journey | Create a new journey (defaults to DRAFT) |
get_journey | Get a journey by ID (draft, published, or version) |
replace_journey | Replace a journey draft (full document replacement) |
publish_journey | Publish a journey draft to make it live and invokable |
archive_journey | Archive a journey |
list_journey_versions | List published versions of a journey |
cancel_journey | Cancel journey runs by cancelation token or run ID |
list_journey_templates | List notification templates scoped to a journey |
create_journey_template | Create a notification template scoped to a journey |
get_journey_template | Get a journey-scoped notification template |
replace_journey_template | Replace a journey-scoped notification template draft |
archive_journey_template | Archive a journey-scoped notification template |
publish_journey_template | Publish a journey-scoped notification template draft |
list_journey_template_versions | List versions of a journey-scoped notification template |
get_journey_template_content | Get the elemental content of a journey-scoped template |
put_journey_template_content | Replace the elemental content of a journey-scoped template |
put_journey_template_locale | Set locale-specific content for a journey-scoped template |
Requests
| Tool | Description |
|---|---|
archive_request | Archive a send request |
Providers
| Tool | Description |
|---|---|
list_providers | List all configured providers in your workspace |
get_provider | Get a configured provider by key |
list_provider_catalog | List all available providers in the Courier catalog |
create_provider | Configure a new provider |
update_provider | Update a configured provider |
delete_provider | Delete a configured provider |
Translations
| Tool | Description |
|---|---|
get_translation | Get a translation for a locale |
update_translation | Create or update a translation |
Inbound
| Tool | Description |
|---|---|
track_inbound_event | Track an inbound event that can trigger automations |
Audit Events
| Tool | Description |
|---|---|
get_audit_event | Get a specific audit event |
list_audit_events | List audit events |
Preference Sections
| Tool | Description |
|---|---|
list_preference_sections | List the workspace’s preference sections and their topics |
create_preference_section | Create a preference section |
get_preference_section | Get a preference section by ID |
replace_preference_section | Replace a preference section |
archive_preference_section | Archive an empty preference section |
publish_preferences | Publish the workspace preferences page |
list_preference_topics | List the topics in a preference section |
create_preference_topic | Create a subscription topic inside a section |
get_preference_topic | Get a topic within a section |
replace_preference_topic | Replace a topic within a section |
archive_preference_topic | Archive a topic within a section |
Digests
| Tool | Description |
|---|---|
release_digest | Release a digest schedule early instead of waiting for its scheduled time |
list_digest_instances | List the digest instances accumulated for a schedule |
Utility
| Tool | Description |
|---|---|
courier_installation_guide | Get SDK installation guide for any platform |
Diagnostic (local installs only)
| Tool | Description |
|---|---|
get_environment_config | Check which API key, base URL, and package version the MCP session is using |
Error Handling
All tools return structured error responses when something goes wrong. Errors from the Courier API include the HTTP status code and message:{
"error": true,
"status": 404,
"message": "Profile not found"
}
400 (bad request), 401 (invalid API key), 404 (resource not found), 429 (rate limited).
What’s Next
Manage Templates (CLI & MCP)
Step-by-step tutorial: create, publish, send, and archive templates from MCP
AI Developer Tools
Overview of all Courier AI tools
CLI
Courier CLI for terminal workflows
Courier Skills
Best-practice guides for AI agents
API Reference
Full Courier API documentation