npm package: @relayrail/server
Description: RelayRail MCP Server - SMS/Email connectivity for AI agents
Author: RelayRail
Latest version: 0.1.9

# @relayrail/server

RelayRail MCP Server - SMS and email connectivity for AI agents via Model Context Protocol.

## Installation

```bash
# Use with npx (recommended)
npx @relayrail/server

# Or install globally
npm install -g @relayrail/server
```

## Quick Start

### 1. Get your API key

Sign up at [relayrail.dev](https://relayrail.dev) and create an agent to get your API key.

### 2. Configure your MCP client

**Claude Code (CLI):**

```bash
claude mcp add relayrail \
  -e RELAYRAIL_API_KEY=rr_your_api_key \
  -- npx @relayrail/server
```

**Claude Desktop:**

Add to your config file (`~/.config/claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "relayrail": {
      "command": "npx",
      "args": ["@relayrail/server"],
      "env": {
        "RELAYRAIL_API_KEY": "rr_your_api_key"
      }
    }
  }
}
```

**Cursor / Cline:**

Same JSON format as above in your MCP settings.

## Available Tools

| Tool | Description |
|------|-------------|
| `request_approval` | Request user approval with custom options (Yes/No or custom choices) |
| `send_notification` | Send a one-way notification to the user (no response expected) |
| `await_response` | Wait for a user response to a previous approval request |
| `get_pending_commands` | Retrieve commands sent by the user via SMS/email |
| `register_agent` | Self-register a new agent (if no API key configured) |
| `get_account_status` | Check quota usage and account status |

### Tool Parameters

**`request_approval`**
- `message` (required): The approval request message
- `options`: Custom response options (default: `["Yes", "No"]`)
- `severity`: `"info"` | `"warning"` | `"critical"` - affects notification priority
- `timeout_minutes`: How long to wait for response (default: 60, max: 1440)
- `context`: Additional context data (object)

**`send_notification`**
- `message` (required): The notification message
- `severity`: `"info"` | `"warning"` | `"critical"`
- `context`: Additional context data (object)

**`await_response`**
- `request_id` (required): The request_id from a previous `request_approval` call
- `timeout_seconds`: How long to wait (default: 30, max: 300)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `RELAYRAIL_API_KEY` | Yes | Your agent's API key from relayrail.dev |
| `RELAYRAIL_BASE_URL` | No | Override API endpoint (default: https://www.relayrail.dev) |
| `RELAYRAIL_DEBUG` | No | Enable debug logging (set to `true`) |

> **Note:** You only need `RELAYRAIL_API_KEY`. The server automatically routes messages through the RelayRail API - no local Telnyx or Resend credentials required.

## How It Works

1. Your agent calls a tool like `request_approval`
2. RelayRail sends an SMS or email to the user (based on their preferences)
3. The user responds via the link or by replying directly
4. Your agent retrieves the response with `await_response`

All message delivery is handled by the RelayRail service - you don't need to configure any SMS or email providers.

## Documentation

Full documentation available at [relayrail.dev/docs](https://relayrail.dev/docs)

## License

MIT