notify MCP server

The notify server is the agent’s outbound channel — it sends messages to the user through whatever integrations the user has configured. Always available (when INTERNAL_SERVER_URL is set).

The single tool

`notify_user`

{
  "message": "Your statement is due in 5 days. $267 minimum.",
  "channel": "telegram:int_gXuDla4UZipcm2tg3McPX",
  "urgency": "normal",
  "claim_thread": true,
  "claim_thread_label": "cc-payment"
}

Arguments

Field	Type	Notes
`message`	string (required)	Plain text or markdown. Channel-specific rendering applied server-side.
`channel`	string	Either a bare type (`slack`, `email`, `webhook`, `telegram`) or `telegram:<integration_id>` for a specific bot. Omit to use the user’s default.
`urgency`	`low` / `normal` / `high`	Affects rendering (Slack thread color, email subject prefix, etc.). Default `normal`.
`claim_thread`	boolean	Telegram-only. Adds `[📎 Reply here]` `[💬 Keep my chat]` inline buttons so the user’s next reply routes back to this session. See Telegram integration.
`claim_thread_label`	string	Telegram-only. Label used in the auto-claim disclaimer (“[Switched to `<label>` thread]”) when the user replies without tapping.

Returns

{ "content": [{ "type": "text", "text": "Notification sent via telegram:int_…" }] }

On failure, isError: true and the text is the error reason.

Routing

For each call the platform:

Resolves the channel. Bare type → user’s first integration of that type. telegram:<id> → that specific integration.
Checks the integration is granted to the running profile (scope=all or profile in profile_ids).
Decrypts the config (bot token / API key / webhook URL).
Sends. For Telegram with claim_thread=true, inserts a telegram_playbook_threads row keyed on the returned Telegram message_id.
Logs to notification_log (success or failure).

Authentication

Authorization: Bearer notify_<token> — minted by the orchestrator. The bearer carries { userId, sessionId }. sessionId always comes from the token, never from agent args — this is what makes claim_thread=true safe: the agent can’t claim sessions it doesn’t own.

When to use notify_user vs platform auto-notify

Use notify_user for: anything mid-run; anything that needs Telegram thread-claim; conditional skipping; multi-message output.
Use platform auto-notify (notify_on: completion on the playbook) for: simple “task done, here’s the result” pings where the agent’s final text is the whole message.

For the patterns in practice, see Playbooks.