RelayRailRelayRail
Documentation
RelayRailRelayRail

API REFERENCE

MCP Tools Reference

Complete reference for all RelayRail MCP tools and their parameters.

Authentication

Tools

Webhooks

Rate Limits

Errors

Authentication

RelayRail uses API keys for authentication. Include your API key in the MCP server configuration:

{
  "mcpServers": {
    "relayrail": {
      "command": "npx",
      "args": ["@relayrail/server", "start"],
      "env": {
        "RELAYRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

register_agent

Register this agent with RelayRail to receive an API key. Use this first if you do not have credentials.

Parameters

namerequired
string

A descriptive name for this agent instance

user_emailrequired
string

Email of the user who will own this agent

Returns

{ success: boolean, api_key?: string, agent_id?: string, error?: string, signup_url?: string }

request_approval

Request approval from a human before proceeding with an action. The user receives an SMS or email with the request.

Parameters

messagerequired
string

The approval request message

options
string[]

Custom response options (default: ["Yes", "No"])

severity
"info" | "warning" | "critical"

Urgency level - affects notification priority (default: "info")

timeout_minutes
number

How long to wait for response (default: 60, max: 1440)

context
object

Additional context data to include

Returns

{ request_id: string, status: "pending" | "blocked", expires_at: string, user: UserContext, quota?: QuotaInfo }

send_notification

Send a one-way notification to a human (no response expected). Delivered via SMS or email based on user preferences.

Parameters

messagerequired
string

The notification message

severity
"info" | "warning" | "critical"

Urgency level (default: "info")

context
object

Additional context data

Returns

{ request_id: string, status: "pending" | "failed" | "blocked", channel: "email" | "sms", quota?: QuotaInfo }

await_response

Wait for a response to a previously sent approval request. Call this after request_approval.

Parameters

request_idrequired
string

The request_id from request_approval

timeout_seconds
number

How long to wait (default: 30, max: 300)

Returns

{ request_id: string, status: "pending" | "approved" | "rejected" | "expired", response?: { choice: string }, timed_out: boolean }

get_pending_commands

Retrieve commands sent by humans to the agent via SMS or email reply.

Parameters

limit
number

Maximum number of commands to return (default: 10)

Returns

{ commands: Array<{ request_id: string, message: string, received_at: string, channel: "email" | "sms" }> }

get_account_status

Check your account status, remaining quotas, and notification preferences.

Parameters

Returns

{ user: UserContext, quotas: { email: QuotaInfo, sms: QuotaInfo }, preferences: { preferred_channel: string } }

Webhooks

RelayRail uses webhooks to receive SMS replies and payment events. Configure these endpoints in your provider dashboards.

Telnyx SMS Webhook

POST /api/webhooks/telnyx

Receives inbound SMS messages and delivery status updates. Configure this URL in your Telnyx Messaging Profile.

Resend Email Webhook

POST /api/webhooks/resend

Receives inbound email replies and delivery status updates. Configure this URL in your Resend dashboard.

Stripe Billing Webhook

POST /api/webhooks/stripe

Handles subscription events and payment confirmations. Configure this URL in your Stripe webhook settings.

Rate Limits

PlanRequests/minSMS/monthEmail/month
Starter ($29)1010010,000
Pro ($99)301,000100,000
Team ($299)605,000 (pooled)500,000

SMS overages: $0.02/msg (Starter), $0.015/msg (Pro/Team). Email overages are negligible.

Error Codes

AUTH_REQUIRED

API key is missing or invalid

RATE_LIMITED

Too many requests, try again later

QUOTA_EXCEEDED

Daily SMS or email quota exceeded

TIMEOUT

Request timed out waiting for response

INVALID_PARAMS

Required parameters missing or invalid