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:

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

1. Sign in at ray.gege.mn and open API keys.
2. 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.
3. 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:

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

Local:

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:

{
  "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:

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

Local:

{
  "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:

{
  "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}):

{
  "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:

[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:

[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:

{
  "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:

{
  "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)

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:

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.