Courier's MCP server lets AI agents send, route, and manage notifications across every channel using the same API your backend uses. This guide covers setup, CLI tooling, Courier Skills, and five real-world patterns with starter prompts you can drop into your IDE.

By "agents" we mean software that runs tasks autonomously. Things like triaging support tickets while you sleep, monitoring data pipelines and paging the on-call engineer when something breaks, processing invoices in batch, syncing enriched profiles back to your CDP. The tooling for this has matured fast. Cursor 3 shipped parallel agents across repos and environments in April 2026. Anthropic launched Claude Managed Agents for long-running autonomous sessions the same week. Windsurf hit 1M+ active users building with agents across 4,000 enterprises. And OpenClaw connected 250K+ developers to local-first agents that control real tools through messaging interfaces, accumulating more GitHub stars in two months than React did in a decade.

All of these agents do things. And when they do things, they need to tell someone what happened. Connect the Courier MCP server to any of these environments and your agent gets /send, /users, /lists, /journeys, /messages, and 55 more tools across the full API surface.

Setup

MCP server (hosted)

Courier hosts the MCP server at https://mcp.courier.com. You need your API key, which you get when you sign up for a free Courier account. Once you're in, grab it from Settings > API Keys.

Claude Code:

claude mcp add Courier --transport http \
  --url https://mcp.courier.com \
  --header "api_key: YOUR_COURIER_API_KEY"

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "Courier": {
      "url": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}

Claude Desktop uses the same JSON structure in claude_desktop_config.json.

Running the MCP connector locally

Courier itself is a hosted platform. But the MCP connector that connects your agent to Courier's API is open source at trycourier/courier-mcp, and you can run it locally if your agent setup requires it (self-hosted agents, VPN requirements, or if you want to gate which tools are exposed).

git clone https://github.com/trycourier/courier-mcp.git
cd courier-mcp
sh dev.sh  # starts at http://localhost:3000

Point your MCP client config to http://localhost:3000 instead of the hosted URL. Your agent still talks to Courier's API for actual notification delivery; the connector is just the bridge between MCP and that API.

Courier CLI

The CLI maps to every API primitive and works in CI/CD pipelines. Install it alongside MCP for workflows where your agent needs to script notification operations. (More on how the CLI fits into agentic workflows in this post.)

npm install -g @trycourier/cli
export COURIER_API_KEY=your_key

# Send a message
courier send message --message '{"to": {"email": "jamie@example.com"}, "content": {"title": "Build failed", "body": "main branch, commit abc1234"}}'

# Check delivery
courier messages list --recipient user_123

# Look up a user
courier users get --user-id user_123

The CLI accepts file input with @filename.ext syntax, supports JSON/YAML output formats, and has a --debug flag that logs full HTTP request/response pairs.

Courier Skills

Separate from the MCP tools, Courier Skills are markdown-based knowledge files that teach your IDE how to build notifications properly. They cover channel-specific best practices (email deliverability, SMS compliance, push payload structure), transactional patterns (auth flows, billing, order confirmations), and growth patterns (onboarding, re-engagement, referrals).

Install them into your IDE's skills directory:

# Cursor (global)
git clone https://github.com/trycourier/courier-skills.git ~/.cursor/skills/courier-skills

# Claude Code
git clone https://github.com/trycourier/courier-skills.git ~/.claude/skills/courier-skills

When your agent builds a notification, the skills provide routing guidance, compliance rules (GDPR, TCPA, CAN-SPAM), and code examples in TypeScript, Python, and curl. Open SKILL.md for the routing table that maps what you're building to the right resource. (More on how Skills work.)

The tools that matter

The MCP server exposes 60 tools. For agent-driven notification workflows, here's the short list:

Pattern 1: Human-in-the-loop (agent needs a decision)

Your agent is doing research, processing data, or running a multi-step workflow. It hits a point where it needs human input before it can continue. Approve a spend, pick between two options, confirm a finding looks right. The agent needs to reach the right person with enough context that they can decide without switching tools.

Starter prompt:

"When you need my input on something, send me a notification through Courier. Check my channel preferences first so it reaches me where I'm actually looking."

Tools the agent uses:

• get_user_preferences -- figure out which channel to reach you on
• send_message -- deliver the question with context
• get_message -- check later if you saw it, escalate channel if not

The agent pauses its workflow, sends a message, and waits. If the notification goes unread, get_message tells the agent it was delivered but not opened, and it can try a different channel.

Pattern 2: Process completion (here's what happened)

The agent ran a job. Data migration, content audit, security scan, invoice reconciliation. It's done and needs to report results to one or more people, potentially with different levels of detail for different audiences.

Starter prompt:

"When you're done, send a summary to the team list in Courier. If anything needs immediate attention, send that separately to the person who owns it with a channel override to push."

Tools the agent uses:

• send_message_to_list -- broadcast the summary to a group
• send_message -- targeted notification to the owner with channel override
• get_message -- verify the urgent one was delivered

For high-volume results (thousands of findings across dozens of users), the agent calls invoke_automation_template per finding and lets a Journey batch them into per-user summaries instead of sending one notification per item.

Pattern 3: Reaching out on the user's behalf

The agent acts as a proxy. It drafts and sends a message to someone else -- a customer, a teammate, a vendor -- on your behalf. You authorized the communication; the agent handles writing and delivery.

Starter prompt:

"Follow up with these users who haven't finished onboarding. Check their profiles to see where they're stuck and send them a nudge using the onboarding-nudge template."

Tools the agent uses:

• get_user_profile_by_id -- see where each customer stalled
• get_user_preferences -- respect their channel opt-ins
• send_message_template -- deliver the nudge with personalized data

CLI for bulk outreach:

for user_id in $(cat user_list.txt); do
  courier users get --user-id "$user_id" --format json
  courier send message --message "{
    \"to\": {\"user_id\": \"$user_id\"},
    \"template\": \"onboarding-nudge\"
  }"
done

This covers any proxy communication: Slack messages to your team, vendor status updates, in-app notifications to customers with their latest report. The agent uses create_or_merge_user to make sure the recipient's contact info is current, then sends.

Pattern 4: Monitoring and threshold alerts (always-on)

The agent watches for a condition and notifies when it's met. Polling an API, watching a metric, waiting for a webhook. Unlike process completion, the agent doesn't finish. It keeps running and alerts when something crosses a line.

Starter prompt:

"Poll this endpoint every 5 minutes. If the value crosses the threshold, notify whoever's on the on-call list in Courier. Escalate the channel if it gets worse."

Tools the agent uses:

• get_list_subscribers -- look up who's on call right now
• send_message_template -- deliver the alert with metric data
• send_message -- direct SMS for critical escalation

What to configure in Journeys: Set up a Journey with a throttle node so your agent doesn't spam the on-call engineer while the error rate stays elevated. The agent fires the event every time it detects a breach; the Journey handles deduplication and rate limiting.

Pattern 5: Profile sync and enrichment

The agent processed something and now has new information about a user. Updated attributes, changed preferences, behavioral signals. It needs to write that data back to Courier so future notifications route correctly and templates personalize properly.

Starter prompt:

"Update the Courier profiles for these users with the new data. For anyone flagged as low-engagement, switch their notification preferences to a channel they're more likely to see."

Tools the agent uses:

• create_or_merge_user -- update profile attributes (merge preserves existing fields)
• update_user_preference_topic -- change routing for specific notification topics

CLI for batch updates:

for user in $(cat updated_users.txt); do
  courier users set --user-id "$user" --profile @"profiles/${user}.json"
done

Every attribute you store on a Courier profile is available in templates, Journeys, and routing rules. When your agent writes preferred_content_type: "technical" to a profile, your product update Journey can branch on it. The enrichment happens once; every notification after that uses it.

Verifying delivery

Across all five patterns, the agent can confirm notifications landed:

• get_message -- delivery status, channel used, provider used
• get_message_history -- full pipeline trace (enqueued, sent, delivered, opened)
• list_messages -- query by recipient, status, or provider

# CLI
courier messages get --message-id msg_abc123
courier messages list --recipient user_8821 --status delivered

If delivery failed, the history shows where it broke. The agent can retry on a different channel or flag it for a human.

Get started

1. Sign up for Courier (free tier: 10,000 notifications/month)
2. Grab your API key from Settings > API Keys
3. Add the MCP server to your IDE (config examples above)
4. Install Courier Skills for channel-specific best practices and compliance guidance
5. Install the CLI for scripting and CI/CD
6. Pick the pattern closest to what your agent does and use the starter prompt

If you need multi-tenant support or outbound webhooks, request a demo to talk through your architecture.

Further reading

• MCP server source (GitHub)
• MCP docs
• CLI docs
• CLI for AI agents (blog)
• Introducing Courier Skills (blog)
• How to Build Notifications with AI (blog)
• AI agent onboarding guide
• Journeys (workflow orchestration)
• User preferences docs
• Full API reference

Sign up free and get your API key in under a minute. Need multi-tenant, outbound webhooks, or want to talk architecture? Request a demo.