Overview
How Windsurf and Courier fit together
Windsurf is an AI code editor with an agent, Cascade, that works across your codebase. With the Courier skill installed, it builds your notification system in your codebase, templates with fallback routing, journeys, preferences, and an in-app inbox, following Courier's patterns for each channel. Courier then makes sure those messages reach people: it picks the channel, falls back when one fails, respects the user's preferences, and shows you what happened.
The skill does the building. Add the hosted MCP server when you want to test against your account from the editor. Windsurf's Cascade agent reads the skill like any other; the MCP server goes in mcp_config.json with serverUrl.
You need a Courier account. The skill needs nothing else; the MCP server needs a test-environment API key, which is separate from production.
What you can build
What you get with Windsurf + Courier
Patterns it reads before it writes
One install. Windsurf opens the skill's router, loads the one or two guides a task needs, and writes sends that follow the rules for that channel: OTP expiry, fallback order, idempotency keys, rate limits.
Templates with fallback routing
Ask for a password-reset flow with SMS first and email fallback and it builds the template and the routing, in your repo, from one prompt.
An in-app inbox in your app
Scaffold the Inbox component into a React or Next.js app and issue the user JWT server-side. The skill's inbox guides carry the auth and rendering patterns.
Journeys with delays and branches
Build a multi-step onboarding journey with a two-day delay between steps, then publish it and run it for a test user.
Preference topics users can opt out of
Create a preference section and topic, publish them, and wire your templates to respect the opt-out.
Test and prototype over MCP
Add the hosted server and Windsurf can create a template in your test workspace, send you a test, and pull the delivery events, so you see the message reach someone before you ship. 144 tools, one config block to add.
Use cases
What to build in your first session
Setup
Set up Windsurf with Courier
Two steps to build. Two more if you want to test against your account from the editor.
npx skills add trycourier/courier-skills
› Add password-reset notifications to this app with Courier: SMS first, email fallback
{
"mcpServers": {
"courier": {
"serverUrl": "https://mcp.courier.com",
"headers": { "api_key": "YOUR_COURIER_API_KEY" }
}
}
}› Publish the password-reset template and send me a test
FAQ
Frequently asked questions
What does the Courier skill add?
A routing file plus about 40 reference guides covering seven channels, transactional and growth patterns, routing, reliability, and Inbox. Windsurf reads the router first and loads only the one or two guides a task needs. It is plain Markdown on the open agent-skills convention, so the same skill works in every tool that reads a SKILL.md.
Do I need the MCP server?
Not to build. The skill is enough for Windsurf to write templates, routing, journeys, and Inbox code in your repo. Add the MCP server when you want to test and prototype against your Courier account from the editor: publish to your test workspace, send yourself a test, read the delivery events.
What can Windsurf do through the Courier MCP server?
The hosted server exposes 144 tools covering the full Courier API: create and publish templates, define routing strategies, build and run journeys, set up preference topics and brands, manage users and lists, send test messages, and read message logs. It authenticates with your API key passed as a header; nothing runs locally.
Why serverUrl and not url?
Windsurf's MCP config names the remote endpoint serverUrl. The value is the same hosted server, https://mcp.courier.com, with your API key in the api_key header.
Is it safe to let it work against my account?
Use the test-environment API key. Test and production keys are separate, so templates, journeys, and test sends stay in the test environment and never reach real users. Switch to the production key when you ship.
How is this different from the Claude and ChatGPT integrations?
Those cover AI assistants: Claude the model inside Courier (AI agent node, AI Translation) and connecting a ChatGPT agent to Courier. This page is Windsurf, the coding tool, building your notification system in your codebase with the Courier skill.
More
