Ray notifications

Official21 tools

by gege-mn · TypeScript

Send email, push, Slack, Discord, Telegram and webhook notifications and manage templates with Ray.

io.github.gege-mn/ray-mcp (MCP Server)

The MCP server “io.github.gege-mn/ray-mcp” provides functionality to send email notifications and dispatch messages to channels including push notifications, Slack, Discord, Telegram, and webhooks. It also manages notification templates using Ray.

🛠️ Key Features

Send email notifications
Send push notifications
Send Slack, Discord, and Telegram notifications
Send webhook notifications
Manage templates with Ray

🚀 Use Cases

Notify users via email and chat platforms
Trigger external integrations via webhooks
Maintain reusable notification templates for consistent messaging

⚡ Developer Benefits

Centralizes notification delivery across multiple services
Supports template management tied to Ray-based workflows

⚠️ Limitations

Limited scope indicated to notification sending and template management with Ray; no additional capabilities are described.

Topics

ai-agentsmcpnotificationspush-notificationsraytransactional-emailtypescript

Captured live from the server via tools/list.

whoami

Identify the API key this connection uses (GET /me): `tenantId` (the workspace), `apiKeyId` and `scopes`. Write tools need the `write` scope; call this to check before attempting them.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_usage

The workspace's plan, subscription status and this calendar month's usage against the monthly quota (GET /billing/subscription). `used`/`remaining` are null on unmetered plans. On a hard-capped plan, sends beyond the quota fail with HTTP 402 quota_exceeded.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_channels

List the delivery channels configured in this workspace (GET /channels). Call this FIRST before sending: each entry's `id` is the `channelConfigId` for send_notification and test_send_template, `kind` is the channel type (ses_email, smtp_email, fcm_push, slack_webhook, discord_webhook, telegram_bot, generic_webhook), `templateKind` is the template channelKind it accepts, and `recipientSchema` is the exact JSON Schema of the `recipient` it expects. Channels and their provider credentials are set up in the Ray dashboard, not through this API; if the list is empty, ask the user to add one there.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

send_notification

Send a notification (POST /send; needs a `write`-scoped key). Returns `{ sendId }` with HTTP 202: delivery is asynchronous, so check the outcome with get_send_status. Use exactly one mode: 1. Single: `channelConfigId` + `recipient`. 2. Fan-out: `channelConfigId` + `targets` (1-1000 `{ recipient, externalUserId? }`), one channel, one sendId. 3. Multi-channel: `deliveries` (1-10, each with its own `channelConfigId`, `recipient` and `templateId` or `content`) for ONE person over several channels; add `feed` + `externalUserId` for a single in-app feed entry. 4. Feed-only: `feed` (with `title`) + `externalUserId` and no channel: an in-app notification only. In modes 1-2 give exactly one of `templateId` (a published template, plus `params`) or inline `content`; in mode 3 that choice is made per delivery. Get channel ids and each recipient shape from list_channels first. Pass `idempotencyKey` whenever a retry must not deliver twice.

Parameters17

channelConfigId	string	optional	Modes 1-2: the channel to send through — an `id` from list_channels. Not allowed together with `deliveries`.
recipient	object	optional	Mode 1: the single recipient. Mutually exclusive with `targets`. Channel-specific delivery target. Its shape depends on the kind of the chosen channel (list_channels returns each channel's exact `recipientSchema`): ses_email / smtp_email → `{ email, name?, cc?: [{ email, name? }], bcc?: [...], attachments?: [{ filename, content (base64), contentType?, disposition?: "attachment"\|"inline", contentId? }] }`; fcm_push → `{ deviceToken }` OR `{ topic }` (exactly one; Ray keeps no device registry); telegram_bot → `{ chatId }` (numeric id as a string, or "@channelname"); slack_webhook, discord_webhook, generic_webhook → `{}` (the destination is part of the channel config).
targets	array	optional	Mode 2: fan-out to 1-1000 recipients over ONE channel, sharing one sendId. Mutually exclusive with `recipient`.
deliveries	array	optional	Mode 3: the same notification to ONE person over several channels (e.g. push + email), max 10. Each entry has its own channel, recipient and content source. Do not combine with top-level channelConfigId/recipient/targets/templateId/content.
templateId	string	optional	Modes 1-2: a PUBLISHED template to render (see list_templates / publish_template). Exactly one of `templateId` or `content`. Its channelKind must match the channel's `templateKind`.
content	object	optional	Inline message content, used INSTEAD of `templateId` (give exactly one of the two). Shape by channel kind: ses_email / smtp_email → `{ subject, bodyHtml, bodyText }`; fcm_push → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_webhook → `{ text }` (Slack mrkdwn); discord_webhook → `{ content }` (max 2000 chars); telegram_bot → `{ text, disableLinkPreview? }` (Telegram HTML subset); generic_webhook → `{ title, body, data?: { [key]: string } }`. `{{name}}` placeholders are filled from `params` and escaped for the channel.
params	object	optional	Values for the template's `{{placeholders}}`. Any JSON: strings, numbers, booleans, arrays and nested objects (arrays/objects drive `{{#section}}…{{/section}}` blocks). Missing required params are rejected with a 400 naming them.
logTitle	string	optional	Feed/log title for inline `content` sends only (template sends take it from the template). Placeholders allowed.
logDescription	string	optional	Feed/log description for inline `content` sends only. Placeholders allowed.
feed	object	optional	Create exactly ONE in-app feed entry for `externalUserId` (read back with list_feed_notifications). `title`/`description` default to the rendered template text; `title` is required for a feed-only send (mode 4).
externalUserId	string	optional	Your own id for the end user. Required with `feed`; keys their in-app feed.
showInFeed	boolean	optional	Legacy modes 1-2 flag: also add a feed entry for each target that has an externalUserId. Prefer `feed`. Not valid with `deliveries`.
trackClicks	boolean	optional	Email channels only: rewrite links in bodyHtml so clicks are counted (read with get_click_stats). Default false.
campaignId	string	optional	Free-form campaign id used to group click stats across sends.
notBefore	string	optional	Schedule delivery for later: ISO 8601 datetime with offset, e.g. "2026-09-15T09:00:00+08:00". Omit to send now.
priority	string	optional	"high" (default) for transactional messages; "low" for marketing/bulk so it never delays transactional sends.
idempotencyKey	string	optional	Sent as the Idempotency-Key header. Retrying with the same key and same arguments returns the original sendId without sending again (24h window); the same key with different arguments fails with 409. Use a fresh unique value (e.g. a UUID) per logical notification.

Raw schema

{
  "type": "object",
  "properties": {
    "channelConfigId": {
      "description": "Modes 1-2: the channel to send through — an `id` from list_channels. Not allowed together with `deliveries`.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "recipient": {
      "description": "Mode 1: the single recipient. Mutually exclusive with `targets`. Channel-specific delivery target. Its shape depends on the kind of the chosen channel (list_channels returns each channel's exact `recipientSchema`): ses_email / smtp_email → `{ email, name?, cc?: [{ email, name? }], bcc?: [...], attachments?: [{ filename, content (base64), contentType?, disposition?: \"attachment\"|\"inline\", contentId? }] }`; fcm_push → `{ deviceToken }` OR `{ topic }` (exactly one; Ray keeps no device registry); telegram_bot → `{ chatId }` (numeric id as a string, or \"@channelname\"); slack_webhook, discord_webhook, generic_webhook → `{}` (the destination is part of the channel config).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "targets": {
      "description": "Mode 2: fan-out to 1-1000 recipients over ONE channel, sharing one sendId. Mutually exclusive with `recipient`.",
      "minItems": 1,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "Channel-specific delivery target. Its shape depends on the kind of the chosen channel (list_channels returns each channel's exact `recipientSchema`): ses_email / smtp_email → `{ email, name?, cc?: [{ email, name? }], bcc?: [...], attachments?: [{ filename, content (base64), contentType?, disposition?: \"attachment\"|\"inline\", contentId? }] }`; fcm_push → `{ deviceToken }` OR `{ topic }` (exactly one; Ray keeps no device registry); telegram_bot → `{ chatId }` (numeric id as a string, or \"@channelname\"); slack_webhook, discord_webhook, generic_webhook → `{}` (the destination is part of the channel config)."
          },
          "externalUserId": {
            "description": "Your own id for this recipient. With `feed`/`showInFeed` they also get an in-app feed entry.",
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        },
        "required": [
          "recipient"
        ]
      }
    },
    "deliveries": {
      "description": "Mode 3: the same notification to ONE person over several channels (e.g. push + email), max 10. Each entry has its own channel, recipient and content source. Do not combine with top-level channelConfigId/recipient/targets/templateId/content.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "channelConfigId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Channel for this delivery (from list_channels)."
          },
          "recipient": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "Channel-specific delivery target. Its shape depends on the kind of the chosen channel (list_channels returns each channel's exact `recipientSchema`): ses_email / smtp_email → `{ email, name?, cc?: [{ email, name? }], bcc?: [...], attachments?: [{ filename, content (base64), contentType?, disposition?: \"attachment\"|\"inline\", contentId? }] }`; fcm_push → `{ deviceToken }` OR `{ topic }` (exactly one; Ray keeps no device registry); telegram_bot → `{ chatId }` (numeric id as a string, or \"@channelname\"); slack_webhook, discord_webhook, generic_webhook → `{}` (the destination is part of the channel config)."
          },
          "templateId": {
            "description": "Published template for this delivery. Exactly one of `templateId` or `content`.",
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "content": {
            "description": "Inline message content, used INSTEAD of `templateId` (give exactly one of the two). Shape by channel kind: ses_email / smtp_email → `{ subject, bodyHtml, bodyText }`; fcm_push → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_webhook → `{ text }` (Slack mrkdwn); discord_webhook → `{ content }` (max 2000 chars); telegram_bot → `{ text, disableLinkPreview? }` (Telegram HTML subset); generic_webhook → `{ title, body, data?: { [key]: string } }`. `{{name}}` placeholders are filled from `params` and escaped for the channel.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "params": {
            "description": "Params for this delivery; falls back to the top-level `params`.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "logTitle": {
            "description": "Feed/log title; only valid with inline `content`.",
            "type": "string",
            "maxLength": 500
          },
          "logDescription": {
            "description": "Feed/log description; only valid with inline `content`.",
            "type": "string",
            "maxLength": 2000
          }
        },
        "required": [
          "channelConfigId",
          "recipient"
        ]
      }
    },
    "templateId": {
      "description": "Modes 1-2: a PUBLISHED template to render (see list_templates / publish_template). Exactly one of `templateId` or `content`. Its channelKind must match the channel's `templateKind`.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "content": {
      "description": "Inline message content, used INSTEAD of `templateId` (give exactly one of the two). Shape by channel kind: ses_email / smtp_email → `{ subject, bodyHtml, bodyText }`; fcm_push → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_webhook → `{ text }` (Slack mrkdwn); discord_webhook → `{ content }` (max 2000 chars); telegram_bot → `{ text, disableLinkPreview? }` (Telegram HTML subset); generic_webhook → `{ title, body, data?: { [key]: string } }`. `{{name}}` placeholders are filled from `params` and escaped for the channel.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "params": {
      "description": "Values for the template's `{{placeholders}}`. Any JSON: strings, numbers, booleans, arrays and nested objects (arrays/objects drive `{{#section}}…{{/section}}` blocks). Missing required params are rejected with a 400 naming them.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "logTitle": {
      "description": "Feed/log title for inline `content` sends only (template sends take it from the template). Placeholders allowed.",
      "type": "string",
      "maxLength": 500
    },
    "logDescription": {
      "description": "Feed/log description for inline `content` sends only. Placeholders allowed.",
      "type": "string",
      "maxLength": 2000
    },
    "feed": {
      "description": "Create exactly ONE in-app feed entry for `externalUserId` (read back with list_feed_notifications). `title`/`description` default to the rendered template text; `title` is required for a feed-only send (mode 4).",
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 500
        },
        "description": {
          "type": "string",
          "maxLength": 2000
        }
      }
    },
    "externalUserId": {
      "description": "Your own id for the end user. Required with `feed`; keys their in-app feed.",
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "showInFeed": {
      "description": "Legacy modes 1-2 flag: also add a feed entry for each target that has an externalUserId. Prefer `feed`. Not valid with `deliveries`.",
      "type": "boolean"
    },
    "trackClicks": {
      "description": "Email channels only: rewrite links in bodyHtml so clicks are counted (read with get_click_stats). Default false.",
      "type": "boolean"
    },
    "campaignId": {
      "description": "Free-form campaign id used to group click stats across sends.",
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "notBefore": {
      "description": "Schedule delivery for later: ISO 8601 datetime with offset, e.g. \"2026-09-15T09:00:00+08:00\". Omit to send now.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "priority": {
      "description": "\"high\" (default) for transactional messages; \"low\" for marketing/bulk so it never delays transactional sends.",
      "type": "string",
      "enum": [
        "high",
        "low"
      ]
    },
    "idempotencyKey": {
      "description": "Sent as the Idempotency-Key header. Retrying with the same key and same arguments returns the original sendId without sending again (24h window); the same key with different arguments fails with 409. Use a fresh unique value (e.g. a UUID) per logical notification.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_send_status

Delivery status of a send (GET /sends/{id}): `aggregate` counts per status over the whole send (pending, claimed, delivered, failed_retryable, failed_terminal, suppressed) plus one page of per-recipient delivery rows including provider errors. Right after sending, rows are usually `pending`; check again after a few seconds. Feed-only sends have no rows. For more rows, pass the returned `nextCursor` as `cursor`.

Parameters3

sendId	string	required	The `sendId` returned by send_notification or test_send_template.
cursor	string	optional	`nextCursor` from the previous page.
limit	integer	optional	Rows per page (default 50, max 200).

Raw schema

{
  "type": "object",
  "properties": {
    "sendId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The `sendId` returned by send_notification or test_send_template."
    },
    "cursor": {
      "description": "`nextCursor` from the previous page.",
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "description": "Rows per page (default 50, max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "sendId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_templates

List message templates (GET /templates): id, name, folder, channelKind, and `publishedVersionId` (null = never published, so it cannot be sent by templateId yet). Archived templates are hidden unless `includeArchived` is true. Use get_template for content and required params.

Parameters2

folder	string	optional	Only templates in this folder.
includeArchived	boolean	optional	Include archived templates. Default false.

Raw schema

{
  "type": "object",
  "properties": {
    "folder": {
      "description": "Only templates in this folder.",
      "type": "string",
      "maxLength": 200
    },
    "includeArchived": {
      "description": "Include archived templates. Default false.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_template

Get one template with its published version and its current draft (GET /templates/{id}): content, logTitle/logDescription, `requiredParams` a send must supply, and paramOverrides. Read this before update_template_draft, which needs the full body.

Parameters1

templateId

string

required

The template id (UUID).

Raw schema

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The template id (UUID)."
    }
  },
  "required": [
    "templateId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_template

Create a template (POST /templates; write scope). `channelKind` is permanent and must match the channels you'll send through (list_channels `templateKind`). It is saved as an unpublished draft unless `publish: true`; sending by templateId needs a published version (publish_template). Names are unique per workspace including archived templates: a collision returns 409, so unarchive_template the old one instead. Returns `{ id, requiredParams }`. Designed (drag-and-drop) email templates can only be made in the dashboard.

Parameters8

name	string	required	Template name, unique per workspace (archived templates included).
folder	string	optional	Optional folder path for organisation, e.g. "billing".
channelKind	string	required	Which channel family the template renders for. Must match the `templateKind` of the channels you will send through (list_channels). Can't be changed after creation.
content	object	required	Channel-shaped template body; the shape is fixed by `channelKind`: email_html → `{ subject, bodyHtml, bodyText }`; fcm_basic → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_text → `{ text }`; discord_text → `{ content }` (max 2000 chars); telegram_text → `{ text, disableLinkPreview? }`; webhook_json → `{ title, body, data?: { [key]: string } }`. Use `{{name}}` placeholders and `{{#items}}…{{/items}}` sections; the required params are derived from them automatically.
logTitle	string	required	Short title shown in the in-app feed and delivery logs, e.g. "Invoice {{number}} is due". Placeholders allowed.
logDescription	string	required	One-line description for the in-app feed and delivery logs. Placeholders allowed.
paramOverrides	object	optional	Per-param metadata keyed by param name: `{ optional?: boolean, description?: string }`. Mark a placeholder optional so sends may omit it.
publish	boolean	optional	true = publish this version immediately so sends by templateId use it. Default false (saved as draft).

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Template name, unique per workspace (archived templates included)."
    },
    "folder": {
      "description": "Optional folder path for organisation, e.g. \"billing\".",
      "type": "string",
      "maxLength": 200
    },
    "channelKind": {
      "type": "string",
      "enum": [
        "email_html",
        "fcm_basic",
        "slack_text",
        "discord_text",
        "telegram_text",
        "webhook_json"
      ],
      "description": "Which channel family the template renders for. Must match the `templateKind` of the channels you will send through (list_channels). Can't be changed after creation."
    },
    "content": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Channel-shaped template body; the shape is fixed by `channelKind`: email_html → `{ subject, bodyHtml, bodyText }`; fcm_basic → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_text → `{ text }`; discord_text → `{ content }` (max 2000 chars); telegram_text → `{ text, disableLinkPreview? }`; webhook_json → `{ title, body, data?: { [key]: string } }`. Use `{{name}}` placeholders and `{{#items}}…{{/items}}` sections; the required params are derived from them automatically."
    },
    "logTitle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Short title shown in the in-app feed and delivery logs, e.g. \"Invoice {{number}} is due\". Placeholders allowed."
    },
    "logDescription": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "One-line description for the in-app feed and delivery logs. Placeholders allowed."
    },
    "paramOverrides": {
      "description": "Per-param metadata keyed by param name: `{ optional?: boolean, description?: string }`. Mark a placeholder optional so sends may omit it.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "optional": {
            "type": "boolean"
          },
          "description": {
            "type": "string",
            "maxLength": 500
          }
        }
      }
    },
    "publish": {
      "description": "true = publish this version immediately so sends by templateId use it. Default false (saved as draft).",
      "type": "boolean"
    }
  },
  "required": [
    "name",
    "channelKind",
    "content",
    "logTitle",
    "logDescription"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_template_draft

Replace a template's draft (PATCH /templates/{id}; write scope). This is a full replacement, not a partial patch: pass content, logTitle, logDescription and paramOverrides as they should end up (get_template first). `name`, `folder` and `channelKind` are required for validation but not changed (channelKind must equal the original). Live sends keep using the published version until you publish, either with `publish: true` here or publish_template. Fails on archived templates.

Parameters9

templateId	string	required	The template id (UUID).
name	string	required	Template name, unique per workspace (archived templates included).
folder	string	optional	Optional folder path for organisation, e.g. "billing".
channelKind	string	required	Which channel family the template renders for. Must match the `templateKind` of the channels you will send through (list_channels). Can't be changed after creation.
content	object	required	Channel-shaped template body; the shape is fixed by `channelKind`: email_html → `{ subject, bodyHtml, bodyText }`; fcm_basic → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_text → `{ text }`; discord_text → `{ content }` (max 2000 chars); telegram_text → `{ text, disableLinkPreview? }`; webhook_json → `{ title, body, data?: { [key]: string } }`. Use `{{name}}` placeholders and `{{#items}}…{{/items}}` sections; the required params are derived from them automatically.
logTitle	string	required	Short title shown in the in-app feed and delivery logs, e.g. "Invoice {{number}} is due". Placeholders allowed.
logDescription	string	required	One-line description for the in-app feed and delivery logs. Placeholders allowed.
paramOverrides	object	optional	Per-param metadata keyed by param name: `{ optional?: boolean, description?: string }`. Mark a placeholder optional so sends may omit it.
publish	boolean	optional	true = publish this version immediately so sends by templateId use it. Default false (saved as draft).

Raw schema

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The template id (UUID)."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Template name, unique per workspace (archived templates included)."
    },
    "folder": {
      "description": "Optional folder path for organisation, e.g. \"billing\".",
      "type": "string",
      "maxLength": 200
    },
    "channelKind": {
      "type": "string",
      "enum": [
        "email_html",
        "fcm_basic",
        "slack_text",
        "discord_text",
        "telegram_text",
        "webhook_json"
      ],
      "description": "Which channel family the template renders for. Must match the `templateKind` of the channels you will send through (list_channels). Can't be changed after creation."
    },
    "content": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Channel-shaped template body; the shape is fixed by `channelKind`: email_html → `{ subject, bodyHtml, bodyText }`; fcm_basic → `{ title, body, imageUrl?, data?: { [key]: string } }`; slack_text → `{ text }`; discord_text → `{ content }` (max 2000 chars); telegram_text → `{ text, disableLinkPreview? }`; webhook_json → `{ title, body, data?: { [key]: string } }`. Use `{{name}}` placeholders and `{{#items}}…{{/items}}` sections; the required params are derived from them automatically."
    },
    "logTitle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Short title shown in the in-app feed and delivery logs, e.g. \"Invoice {{number}} is due\". Placeholders allowed."
    },
    "logDescription": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "One-line description for the in-app feed and delivery logs. Placeholders allowed."
    },
    "paramOverrides": {
      "description": "Per-param metadata keyed by param name: `{ optional?: boolean, description?: string }`. Mark a placeholder optional so sends may omit it.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "optional": {
            "type": "boolean"
          },
          "description": {
            "type": "string",
            "maxLength": 500
          }
        }
      }
    },
    "publish": {
      "description": "true = publish this version immediately so sends by templateId use it. Default false (saved as draft).",
      "type": "boolean"
    }
  },
  "required": [
    "templateId",
    "name",
    "channelKind",
    "content",
    "logTitle",
    "logDescription"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

publish_template

Publish a template's current draft as its new live version (POST /templates/{id}/publish; write scope). Sends by templateId use it immediately. Fails if there is no draft or the template is archived.

Parameters1

templateId

string

required

The template id (UUID).

Raw schema

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The template id (UUID)."
    }
  },
  "required": [
    "templateId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

archive_template

Archive a template (POST /templates/{id}/archive; write scope). Sends that reference it fail until it is restored with unarchive_template; its name stays reserved meanwhile. Confirm with the user first if it may be in production use.

Parameters1

templateId

string

required

The template id (UUID).

Raw schema

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The template id (UUID)."
    }
  },
  "required": [
    "templateId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

unarchive_template

Restore an archived template (POST /templates/{id}/unarchive; write scope). This is how to reclaim a name held by an archived template instead of creating a new one.

Parameters1

templateId

string

required

The template id (UUID).

Raw schema

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The template id (UUID)."
    }
  },
  "required": [
    "templateId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

test_send_template

Send a real test of a template's PUBLISHED version to one recipient (POST /templates/{id}/test-send; write scope). It goes through the provider for real, so use a recipient the user controls. Test sends don't count toward the monthly quota (a small daily allowance applies instead) and never appear in feeds. Returns `{ sendId }` for get_send_status.

Parameters4

templateId	string	required	The template id (UUID).
channelConfigId	string	required	Channel to test through (from list_channels); its templateKind must match the template's channelKind.
recipient	object	required	Channel-specific delivery target. Its shape depends on the kind of the chosen channel (list_channels returns each channel's exact `recipientSchema`): ses_email / smtp_email → `{ email, name?, cc?: [{ email, name? }], bcc?: [...], attachments?: [{ filename, content (base64), contentType?, disposition?: "attachment"\|"inline", contentId? }] }`; fcm_push → `{ deviceToken }` OR `{ topic }` (exactly one; Ray keeps no device registry); telegram_bot → `{ chatId }` (numeric id as a string, or "@channelname"); slack_webhook, discord_webhook, generic_webhook → `{}` (the destination is part of the channel config).
params	object	optional	Values for the template's `{{placeholders}}`. Any JSON: strings, numbers, booleans, arrays and nested objects (arrays/objects drive `{{#section}}…{{/section}}` blocks). Missing required params are rejected with a 400 naming them.

Raw schema

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The template id (UUID)."
    },
    "channelConfigId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Channel to test through (from list_channels); its templateKind must match the template's channelKind."
    },
    "recipient": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Channel-specific delivery target. Its shape depends on the kind of the chosen channel (list_channels returns each channel's exact `recipientSchema`): ses_email / smtp_email → `{ email, name?, cc?: [{ email, name? }], bcc?: [...], attachments?: [{ filename, content (base64), contentType?, disposition?: \"attachment\"|\"inline\", contentId? }] }`; fcm_push → `{ deviceToken }` OR `{ topic }` (exactly one; Ray keeps no device registry); telegram_bot → `{ chatId }` (numeric id as a string, or \"@channelname\"); slack_webhook, discord_webhook, generic_webhook → `{}` (the destination is part of the channel config)."
    },
    "params": {
      "description": "Values for the template's `{{placeholders}}`. Any JSON: strings, numbers, booleans, arrays and nested objects (arrays/objects drive `{{#section}}…{{/section}}` blocks). Missing required params are rejected with a 400 naming them.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "templateId",
    "channelConfigId",
    "recipient"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_feed_notifications

Read one end user's in-app notification feed (GET /notifications): the entries created by sends with `feed` or `showInFeed`. This is what an in-app inbox would show, not delivery status (use get_send_status for that). Paginate by passing `nextCursor` back as `cursor`.

Parameters7

externalUserId	string	required	The end user whose feed to read (the `externalUserId` used when sending).
templateId	string	optional	Only entries from this template.
channelConfigId	string	optional	Only entries whose first delivery used this channel.
after	string	optional	Only entries created after this ISO 8601 UTC datetime (e.g. "2026-09-01T00:00:00Z").
before	string	optional	Only entries created before this ISO 8601 UTC datetime.
cursor	string	optional	`nextCursor` from the previous page.
limit	integer	optional	Entries per page (default 50, max 200).

Raw schema

{
  "type": "object",
  "properties": {
    "externalUserId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "The end user whose feed to read (the `externalUserId` used when sending)."
    },
    "templateId": {
      "description": "Only entries from this template.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "channelConfigId": {
      "description": "Only entries whose first delivery used this channel.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "after": {
      "description": "Only entries created after this ISO 8601 UTC datetime (e.g. \"2026-09-01T00:00:00Z\").",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "before": {
      "description": "Only entries created before this ISO 8601 UTC datetime.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "cursor": {
      "description": "`nextCursor` from the previous page.",
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "description": "Entries per page (default 50, max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "externalUserId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_click_stats

Email link click counts grouped by destination URL (GET /clicks) for a `sendId`, a `campaignId`, or both (at least one is required). Only links from email sends made with `trackClicks: true` are counted.

Parameters2

sendId	string	optional	A sendId from send_notification.
campaignId	string	optional	The `campaignId` passed to send_notification, to total clicks across many sends.

Raw schema

{
  "type": "object",
  "properties": {
    "sendId": {
      "description": "A sendId from send_notification.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "campaignId": {
      "description": "The `campaignId` passed to send_notification, to total clicks across many sends.",
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_webhooks

List the workspace's outbound event webhooks (GET /tenant-webhooks): url, subscribed events, enabled flag and delivery health (consecutiveFailures, lastError). Signing secrets are never returned.

Parameters1

includeArchived

boolean

optional

Include deleted (archived) webhooks. Default false.

Raw schema

{
  "type": "object",
  "properties": {
    "includeArchived": {
      "description": "Include deleted (archived) webhooks. Default false.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_webhook

Get one outbound webhook (GET /tenant-webhooks/{id}) including its delivery health (consecutiveFailures, lastDeliveryAt, lastFailureAt, lastError).

Parameters1

webhookId

string

required

The webhook id (UUID).

Raw schema

{
  "type": "object",
  "properties": {
    "webhookId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The webhook id (UUID)."
    }
  },
  "required": [
    "webhookId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_webhook

Create an outbound webhook that Ray POSTs signed event payloads to (POST /tenant-webhooks; write scope; Pro plan or higher, otherwise 403). The URL must be public HTTPS. The response contains the signing `secret` exactly once: show it to the user to store (e.g. as an env var), since it can't be read again, only rotated with update_webhook. Read the `webhooks` docs page for the signature scheme.

Parameters3

name	string	required	Label for the webhook, e.g. "Production delivery events".
url	string	required	Public HTTPS endpoint that will receive the events.
events	array	required	Events to receive: "notification.delivered", "notification.failed_terminal" (one per recipient), and "send.completed" (once per send, with status totals).

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Label for the webhook, e.g. \"Production delivery events\"."
    },
    "url": {
      "type": "string",
      "description": "Public HTTPS endpoint that will receive the events."
    },
    "events": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "notification.delivered",
          "notification.failed_terminal",
          "send.completed"
        ]
      },
      "description": "Events to receive: \"notification.delivered\", \"notification.failed_terminal\" (one per recipient), and \"send.completed\" (once per send, with status totals)."
    }
  },
  "required": [
    "name",
    "url",
    "events"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_webhook

Change a webhook (PATCH /tenant-webhooks/{id}; write scope). Only the fields you pass change; pass at least one. `rotateSecret: true` issues a new signing secret, returned once in the response, and the old secret stops verifying immediately, so the receiving service must be updated at the same time.

Parameters6

webhookId	string	required	The webhook id (UUID).
name	string	optional	New label.
url	string	optional	New public HTTPS endpoint.
events	array	optional	Replaces the subscribed events. Events to receive: "notification.delivered", "notification.failed_terminal" (one per recipient), and "send.completed" (once per send, with status totals).
enabled	boolean	optional	false pauses deliveries without deleting the webhook.
rotateSecret	boolean	optional	true rotates the signing secret (new secret returned once; old one invalid immediately).

Raw schema

{
  "type": "object",
  "properties": {
    "webhookId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The webhook id (UUID)."
    },
    "name": {
      "description": "New label.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "url": {
      "description": "New public HTTPS endpoint.",
      "type": "string"
    },
    "events": {
      "description": "Replaces the subscribed events. Events to receive: \"notification.delivered\", \"notification.failed_terminal\" (one per recipient), and \"send.completed\" (once per send, with status totals).",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "notification.delivered",
          "notification.failed_terminal",
          "send.completed"
        ]
      }
    },
    "enabled": {
      "description": "false pauses deliveries without deleting the webhook.",
      "type": "boolean"
    },
    "rotateSecret": {
      "description": "true rotates the signing secret (new secret returned once; old one invalid immediately).",
      "type": "boolean"
    }
  },
  "required": [
    "webhookId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_webhook

Delete (archive) a webhook so it receives no more events (DELETE /tenant-webhooks/{id}; write scope). It cannot be restored through the API; confirm with the user first.

Parameters1

webhookId

string

required

The webhook id (UUID).

Raw schema

{
  "type": "object",
  "properties": {
    "webhookId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The webhook id (UUID)."
    }
  },
  "required": [
    "webhookId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

read_docs

Read Ray's documentation as markdown. With no `slug` it returns the index (llms.txt) listing every page; then pass a page slug, i.e. the path after /docs/ without `.md`, such as `sending`, `templates`, `idempotency`, `errors`, `rate-limits`, `webhooks`, `status-and-feeds` or `channels/telegram`. Use it for anything the tool descriptions don't cover.

Parameters1

slug

string

optional

Page slug like "sending" or "channels/push-fcm". Omit for the index of all pages.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "description": "Page slug like \"sending\" or \"channels/push-fcm\". Omit for the index of all pages.",
      "type": "string",
      "maxLength": 100
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md12 KBView on GitHub

Ray MCP server

MCP server for Ray, the notification delivery API. It lets Claude, Cursor, VS Code, Windsurf, Codex, Zed and any other MCP client send notifications and manage templates, delivery webhooks and usage in your Ray workspace.

Ray here is the multi-tenant notification API from gege.mn (email via Amazon SES or SMTP, Firebase push, Slack, Discord, Telegram, SMS via Twilio or sendsms.mn, generic webhooks and an in-app feed). It is not the Ray distributed computing framework.

Hosted or local?

Ray runs an MCP server for you. There are two ways to connect, with the same tools:

	Hosted (recommended)	Local (this package)
What runs	Nothing on your machine	`npx -y @gege-mn/ray-mcp`, a stdio process
Endpoint	`https://ray-api.gege.mn/mcp` (Streamable HTTP)	Bridges to the hosted endpoint
Auth	`Authorization: Bearer <key>` header	`RAY_API_KEY` environment variable
Use it when	Your client supports remote servers with custom headers	Your client only runs stdio servers (e.g. Claude Desktop config file), or you prefer env vars over headers

This package is a thin bridge: it connects to the hosted endpoint with your key and mirrors its tool list, descriptions and instructions, so new tools appear without upgrading the package. All validation, scopes, rate limits and quota are enforced by Ray's API.

1. Get an API key

Sign in at ray.gege.mn and open API keys.
Create a key. It starts with ck_live_ and is shown only once.
- read scope: status, templates, usage, docs.
- write scope: also needed to send, create or change templates, and manage webhooks.
Configure at least one channel in the dashboard under Channels. Channel credentials can't be created through the API or MCP.

The examples below use ck_live_... as a placeholder. Keep real keys out of version control.

2. Add Ray to your client

Claude Code

Hosted:

bash

claude mcp add --transport http ray https://ray-api.gege.mn/mcp --header "Authorization: Bearer $RAY_API_KEY"

Local:

bash

claude mcp add ray --env RAY_API_KEY=ck_live_... -- npx -y @gege-mn/ray-mcp

Add --scope user to make it available in every project. Check the connection with claude mcp get ray.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config; macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json), then fully restart Claude Desktop:

json

{
  "mcpServers": {
    "ray": {
      "command": "npx",
      "args": ["-y", "@gege-mn/ray-mcp"],
      "env": { "RAY_API_KEY": "ck_live_..." }
    }
  }
}

Cursor

.cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects.

Hosted:

json

{
  "mcpServers": {
    "ray": {
      "url": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ck_live_..." }
    }
  }
}

Local:

json

{
  "mcpServers": {
    "ray": {
      "command": "npx",
      "args": ["-y", "@gege-mn/ray-mcp"],
      "env": { "RAY_API_KEY": "ck_live_..." }
    }
  }
}

Cursor can read the key from your environment instead: "Authorization": "Bearer ${env:RAY_API_KEY}".

VS Code (GitHub Copilot)

VS Code's mcp.json (.vscode/mcp.json in a workspace, or MCP: Open User Configuration) uses a top-level servers key and can prompt for the key so it isn't stored in the file:

json

{
  "inputs": [
    { "id": "ray-api-key", "type": "promptString", "description": "Ray API key (ck_live_...)", "password": true }
  ],
  "servers": {
    "ray": {
      "type": "http",
      "url": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ${input:ray-api-key}" }
    }
  }
}

Local variant: replace the server entry with { "type": "stdio", "command": "npx", "args": ["-y", "@gege-mn/ray-mcp"], "env": { "RAY_API_KEY": "${input:ray-api-key}" } }.

Windsurf

~/.codeium/windsurf/mcp_config.json (Windsurf calls the URL field serverUrl and supports ${env:VAR}):

json

{
  "mcpServers": {
    "ray": {
      "serverUrl": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ${env:RAY_API_KEY}" }
    }
  }
}

Local: use the same command / args / env entry as in the Cursor example.

Codex

~/.codex/config.toml, local:

toml

[mcp_servers.ray]
command = "npx"
args = ["-y", "@gege-mn/ray-mcp"]
env = { RAY_API_KEY = "ck_live_..." }

Hosted, reading the key from your shell environment:

toml

[mcp_servers.ray]
url = "https://ray-api.gege.mn/mcp"
bearer_token_env_var = "RAY_API_KEY"

Or from the CLI: codex mcp add ray --env RAY_API_KEY=ck_live_... -- npx -y @gege-mn/ray-mcp.

Zed

In Zed's settings.json:

json

{
  "context_servers": {
    "ray": {
      "url": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ck_live_..." }
    }
  }
}

Local: "ray": { "command": "npx", "args": ["-y", "@gege-mn/ray-mcp"], "env": { "RAY_API_KEY": "ck_live_..." } }.

Any other client

Any client that runs stdio servers:

json

{
  "mcpServers": {
    "ray": {
      "command": "npx",
      "args": ["-y", "@gege-mn/ray-mcp"],
      "env": { "RAY_API_KEY": "ck_live_..." }
    }
  }
}

Any client that supports Streamable HTTP: URL https://ray-api.gege.mn/mcp, header Authorization: Bearer ck_live_....

Environment variables (local package)

Variable	Required	Default	Description
`RAY_API_KEY`	yes		Ray API key (`ck_live_...`). Whitespace, quotes and a `Bearer` prefix are stripped.
`RAY_MCP_URL`	no	`https://ray-api.gege.mn/mcp`	Hosted endpoint to bridge to. Only change it for staging or local development.

CLI flags: --help, --version. Requires Node.js 18 or newer.

Tools

The tool list comes from the hosted server, so it can grow over time; your client shows the authoritative descriptions and input schemas. Current tools:

Tool	What it does
`whoami`	Shows the workspace, key id and scopes of the API key in use.
`get_usage`	Plan, subscription status and this month's usage against the quota.
`list_channels`	Configured channels with their ids and the recipient shape each accepts. Call first.
`send_notification`	Sends a notification (single, fan-out, multi-channel or feed-only). Needs `write`.
`get_send_status`	Delivery status of a send, with per-recipient rows.
`list_templates`	Lists message templates.
`get_template`	One template with its published version and draft.
`create_template`	Creates a template, optionally publishing it. Needs `write`.
`update_template_draft`	Replaces a template's draft. Needs `write`.
`publish_template`	Publishes a template's draft as the live version. Needs `write`.
`archive_template`	Archives a template. Needs `write`.
`unarchive_template`	Restores an archived template. Needs `write`.
`test_send_template`	Sends a real test of a published template to one recipient. Needs `write`.
`list_feed_notifications`	Reads one end user's in-app notification feed.
`get_click_stats`	Email link click counts for a send or campaign.
`list_webhooks`	Lists outbound event webhooks and their delivery health.
`get_webhook`	One outbound webhook.
`create_webhook`	Creates an outbound webhook; returns its signing secret once. Needs `write`.
`update_webhook`	Changes a webhook or rotates its secret. Needs `write`.
`delete_webhook`	Deletes a webhook. Needs `write`.
`read_docs`	Reads Ray's documentation as markdown.

Read-only tools are annotated readOnlyHint; archive and delete tools are annotated destructiveHint, so clients can ask before running them.

Example prompts

"Send a test email to me through Ray."
"Which Ray channels do I have, and what recipient does each one need?"
"Create and publish a welcome email template in Ray with a firstName param, then test-send it to me."
"Did send snd_... get delivered? Show me any failures."
"How many notifications have we sent this month, and how much quota is left?"
"Set up a Ray webhook to https://example.com/hooks/ray for failed deliveries."

Troubleshooting

The local package always starts, even when something is wrong, and explains the problem through MCP instead of crashing. Diagnostics go to stderr (your client's MCP log); stdout carries only MCP messages.

Only a setup_help tool is listed. The server can't load Ray's tools. Its description says why. Without RAY_API_KEY every tool call returns setup steps. If the endpoint was unreachable, call setup_help after fixing the cause: it retries, and on success the client is told the tool list changed. If your client doesn't refresh, reload the server.
"Ray rejected the API key (HTTP 401)". The key is wrong, revoked, or was pasted incompletely. Create a new key at ray.gege.mn, update the config and restart the client.
"write scope required" or HTTP 403. The key is read-only, or your plan doesn't include the feature (webhooks need Pro or higher). Use a key with the write scope.
HTTP 402 / quota. The workspace used its monthly quota. Check with get_usage.
HTTP 429. Rate limited; the error says how many seconds to wait. See rate limits.
"Could not reach Ray's MCP endpoint (ECONNREFUSED / ENOTFOUND / ...)". Network, proxy or firewall problem, or a wrong RAY_MCP_URL.
npx not found or old Node. Install Node.js 18+ and make sure npx is on the PATH your client uses. On macOS GUI apps may not see shell PATH changes; use an absolute path to npx if needed.
Check the server by hand: RAY_API_KEY=ck_live_... npx -y @gege-mn/ray-mcp should log connected to https://ray-api.gege.mn/mcp on stderr, then wait for input (Ctrl+C to exit). Or inspect it with npx @modelcontextprotocol/inspector npx -y @gege-mn/ray-mcp.

Docs: ray.gege.mn/docs, with an index for agents at ray.gege.mn/llms.txt (append .md to any docs URL for raw markdown). The MCP setup guide is Using Ray with AI coding agents.
API reference: ray-api.gege.mn/docs, OpenAPI at ray-api.gege.mn/openapi.json.
TypeScript SDK: @gege-mn/ray (gege-mn/ray-node).
Agent skills and Claude Code plugin: gege-mn/ray-skills (npx skills add gege-mn/ray-skills).

Development

bash

pnpm install
pnpm typecheck
pnpm test        # vitest: bridge end to end against an in-process fake Ray endpoint
pnpm build       # tsup -> dist/index.js
pnpm smoke       # the built binary over real stdio
RAY_MCP_URL=http://localhost:8787/mcp RAY_API_KEY=ck_live_... node dist/index.js

Releasing: bump the version in package.json, server.json (both version fields) and src/version.ts, update CHANGELOG.md, then publish a GitHub release tagged vX.Y.Z. The publish workflow ships to npm and the MCP Registry. To publish by hand instead: pnpm publish --access public, then run the MCP Registry workflow (a personal mcp-publisher login github can't publish under the gege-mn namespace).

License

MIT © gege.mn

Install

Tools (21)

whoamiget_usagelist_channelssend_notificationget_send_statuslist_templatesget_templatecreate_template

Configuration

Environment variables

RAY_API_KEYrequiredsecret

Ray API key (ck_live_...). Create one at https://ray.gege.mn under API keys; use the write scope to send and edit.

RAY_MCP_URLdefault https://ray-api.gege.mn/mcp

Hosted Ray MCP endpoint to bridge to. Only change this for self-hosted or staging deployments.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ray-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gege-mn/ray-mcp@0.1.0"
      ],
      "env": {
        "RAY_API_KEY": "<YOUR_RAY_API_KEY>",
        "RAY_MCP_URL": "https://ray-api.gege.mn/mcp"
      }
    }
  }
}

io.github.gege-mn/ray-mcp (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

whoami

get_usage

list_channels

send_notification

get_send_status

list_templates

get_template

create_template

update_template_draft

publish_template

archive_template

unarchive_template

test_send_template

list_feed_notifications

get_click_stats

list_webhooks

get_webhook

create_webhook

update_webhook

delete_webhook

read_docs

Ray MCP server

Hosted or local?

1. Get an API key

2. Add Ray to your client

Claude Code

Claude Desktop

Cursor

VS Code (GitHub Copilot)

Windsurf

Codex

Zed

Any other client

Environment variables (local package)

Tools

Example prompts

Troubleshooting

Related

Development

License

Install

Configuration

Related servers