Prerequisite: Create an API Key You need a Courier API key to authenticate MCP requests. Create one in your Courier Settings , then replace YOUR_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 Cursor
Claude Code
Claude Desktop
Windsurf
VSCode
OpenAI API
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.
claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY
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" ] } } }
In Windsurf, go to Windsurf > Windsurf Settings > Manage MCP Servers > View Raw Config , then add: { "mcpServers" : { "courier" : { "serverUrl" : "https://mcp.courier.com" , "headers" : { "api_key" : "YOUR_COURIER_API_KEY" }, "disabled" : false , "disabledTools" : [] } } }
Create .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}" } } } }
Open the chat window, click the Gear icon, then MCP Servers , and start the “courier” server. VS Code works best when prefixing prompts with # in the chat. For example: #get_user_profile_by_id example_user_id.
OpenAI’s Responses API supports MCP servers as tool providers. The input field is the user prompt; the model decides which tools to call based on it. import OpenAI from "openai" ; const client = new OpenAI (); const response = await client . responses . create ({ model: "gpt-4o" , input: "Look up the profile for user-123 and tell me their email" , tools: [ { type: "mcp" , server_label: "courier" , server_url: "https://mcp.courier.com" , headers: { api_key: "YOUR_COURIER_API_KEY" }, require_approval: "never" , }, ], }); console . log ( response . output_text );
The Courier MCP server exposes 60 tools covering the full Courier API surface: 59 default tools plus 1 diagnostic tool available in local installs. All tools are backed by the official @trycourier/courier
Send Tool Description send_messageSend a message using inline title and body content send_message_templateSend a message using a notification template send_message_to_listSend inline content to all subscribers of a list send_message_to_list_templateSend a template to all subscribers of a list
Messages Tool Description list_messagesList sent messages with filters (status, recipient, provider, tags) get_messageGet full details and delivery status of a message get_message_contentGet the rendered HTML, text, and subject of a sent message get_message_historyGet the event history for a message (enqueued, sent, delivered, etc.) cancel_messageCancel a message currently being delivered
Profiles Tool Description get_user_profile_by_idGet a user profile by ID create_or_merge_userCreate or merge values into an existing profile replace_profileFully replace a user profile (PUT) delete_profileDelete a user profile get_user_list_subscriptionsGet all list subscriptions for a user subscribe_user_to_listsSubscribe a user to one or more lists delete_user_list_subscriptionsRemove all list subscriptions for a user
Lists Tool Description list_listsGet all lists, optionally filtered by pattern get_listGet a list by ID get_list_subscribersGet all subscribers of a list create_listCreate or update a list subscribe_user_to_listSubscribe a user to a list unsubscribe_user_from_listUnsubscribe a user from a list
Audiences Tool Description get_audienceGet an audience by ID list_audiencesList all audiences list_audience_membersList members of an audience update_audienceCreate or update an audience with a filter definition delete_audienceDelete an audience
Notifications Tool Description list_notificationsList notification templates get_notification_contentGet published content blocks of a template get_notification_draft_contentGet draft content blocks of a template
Brands Tool Description create_brandCreate a new brand get_brandGet a brand by ID list_brandsList all brands
Auth & Tokens Tool Description generate_jwt_for_userGenerate a JWT token for client-side SDK auth list_user_push_tokensList all push/device tokens for a user get_user_push_tokenGet a specific push token create_or_replace_user_push_tokenCreate or replace a push token
Automations Tool Description invoke_automation_templateInvoke an automation from a template invoke_ad_hoc_automationInvoke an ad-hoc automation with inline steps
Bulk Tool Description create_bulk_jobCreate a bulk job for multi-recipient sends add_bulk_usersAdd users to an existing bulk job run_bulk_jobTrigger delivery for a bulk job get_bulk_jobGet the status of a bulk job list_bulk_usersList users in a bulk job
Tenants Tool Description get_tenantGet a tenant by ID create_or_update_tenantCreate or replace a tenant list_tenantsList all tenants delete_tenantDelete a tenant
Users Tool Description get_user_preferencesGet a user’s notification preferences update_user_preference_topicUpdate a user’s preference for a subscription topic list_user_tenantsList all tenants a user belongs to add_user_to_tenantAdd a user to a tenant remove_user_from_tenantRemove a user from a tenant
Translations Tool Description get_translationGet a translation for a locale update_translationCreate or update a translation
Inbound Tool Description track_inbound_eventTrack an inbound event that can trigger automations
Audit Events Tool Description get_audit_eventGet a specific audit event list_audit_eventsList audit events
Utility Tool Description courier_installation_guideGet SDK installation guide for any platform
Diagnostic (local installs only) Tool Description get_environment_configCheck 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" }
Common error codes: 400 (bad request), 401 (invalid API key), 404 (resource not found), 429 (rate limited).
What’s Next
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
