Documentation

MCP server and REST API reference for Relay tools.

MCP server

Endpoint

https://getrelay.us/api/mcp

Authentication

Authorization: Bearer relay_your_key

Claude Desktop config

{
  "mcpServers": {
    "relay": {
      "url": "https://getrelay.us/api/mcp",
      "headers": {
        "Authorization": "Bearer relay_your_key_here"
      }
    }
  }
}

Direct API call (cURL)

curl -X POST https://getrelay.us/api/mcp \
  -H "Authorization: Bearer relay_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_rates",
      "arguments": {
        "from_zip": "10001",
        "to_zip": "90210",
        "to_country": "US",
        "weight_oz": 12,
        "length_in": 10,
        "width_in": 8,
        "height_in": 4
      }
    },
    "id": 1
  }'

Plans and rate limits

Plan	Included API calls	Cost after allotment	Per-minute limit
Starter	1,000 / month	$0.003 / call after allotment	20 / min
Growth	25,000 / month	$0.0025 / call after allotment	100 / min
Scale	100,000 / month	$0.002 / call after allotment	300 / min

Relay is metered through your wallet, not a hard monthly cutoff. Each call deducts from your credit balance; your plan's monthly allotment is included at no charge, and calls beyond it are billed per call at the rate above. Hitting the per-minute limit returns HTTP 429 with a Retry-After header. Running out of credits returns INSUFFICIENT_CREDITS (402) until you top up.

Shipping tools (7)

Direct mail tools (3)

Physical mail is not yet generally available. Until it launches, calls to these tools return "Physical mail is not available yet."

Error codes

Code	HTTP status	Meaning
UNAUTHORIZED	401	Missing or invalid API key.
INSUFFICIENT_CREDITS	402	Account has no credits remaining. Top up your balance.
RATE_LIMITED	429	Too many requests. Back off and retry after the Retry-After header value.
VALIDATION	400	A required parameter is missing or malformed.
INTERNAL_ERROR	500	Something went wrong on our end. Retry once. If it persists, contact support.

All responses follow { data, error, meta }. On success, error is null. On failure, data is null and error.code is one of the values above.