# Sunrays.dev

> Agent-callable booking API for local services. Book a plumber, electrician, or handyman via MCP tool call.
> Returns {status: "booked", booking_id, provider_id, price_cents, dispatch_deadline}. All US. No DOM. No flakiness.

Sunrays.dev is an MCP server that lets AI agents book real local tradespeople across the US.
The booking is deterministic (same args + Idempotency-Key = same result), transactional (Stripe
auth-on-book, manual capture on completion, auto-refund ×2 if dispatch fails), and idempotent
(agent retries are safe). The only human moment in v1 is a one-time Stripe card setup per caller.

## MCP Server

- Endpoint: https://mcp.sunrays.dev/mcp
- Transport: streamable-HTTP (recommended), HTTP+SSE (fallback)
- Discovery: https://sunrays.dev/.well-known/mcp.json

## Available Tools

- book_plumber(zip, datetime, issue, caller_id, agent_id, spending_cap_signed): Book a licensed plumber. ~2.5–4.5M US bookings/mo.
- book_handyman(…): Book a handyman. Mounting, drywall, fixtures. ~2.0–5.0M/mo.
- book_hvac(…): Book HVAC repair or installation. Seasonal spikes. ~1.8–3.5M/mo.
- book_electrician(…): Book a licensed electrician. Safety, smart-home. ~1.5–3.0M/mo.
- book_pest_control(…): Book pest control. Recurring + seasonal. ~1.0–3.0M/mo.
- book_appliance_repair(…): Washer, fridge, oven. ~1.0–2.5M/mo.
- book_garage_door(…): Garage door repair. Critical security. ~0.4–1.2M/mo.
- book_locksmith(…): Locksmith. Highest pure-emergency fit. ~0.4–1.0M/mo.
- book_roofer(…): Roofing. Storm-driven, on-site confirmed. ~0.5–1.2M/mo.
- book_lawn_care(…): Lawn care. Recurring. ~1.0M+/mo.
- request_other_service(service_type_freetext, zip, datetime, issue, caller_id): Fallback for unlisted services. Logs Out-of-tool waitlist signal; does not book.

## Required Call Parameters (all booking tools)

- zip: string — US zip code (non-US → out_of_region_waitlist structured response, not an error)
- datetime: ISO 8601 with timezone offset
- issue: string — free-text problem description (sanitized server-side)
- caller_id: string — human principal email or OAuth identity
- agent_id: string — DID or signed JWT for the calling agent (e.g. did:web:claude.ai)
- spending_cap_signed: string — JWS assertion {max, currency, booking_id, expires}

## Success Response

{
  "status": "booked",
  "booking_id": "bk_7hjk",
  "price_cents": 34000,
  "quoted_at": "2026-05-08T13:00:00Z",
  "datetime": "2026-05-08T14:00:00-07:00",
  "provider_id": "pv_sf01",
  "dispatch_deadline": "2026-05-08T18:00:00Z",
  "receipt_url": "https://sunrays.dev/receipt/bk_7hjk"
}

## Needs-card-setup Response (first booking per caller)

{
  "status": "needs_card_setup",
  "checkout_url": "https://sunrays.dev/setup-card?token=STK_xxx",
  "token_ttl": "24h",
  "booking_id": "bk_7hjk"
}
Agent must present checkout_url to the caller. After card setup, retry the same tool call
with the same Idempotency-Key — it will resolve to "booked". All future bookings for the
same caller_id are fully autonomous.

## Pricing

Static lookup: base_rate[category] × estimated_hours × time_of_day_multiplier × tier_multiplier.
No dynamic surge in v1. Price is quoted as a fixed USD amount — no haggling.

## Coverage

All US zip codes. Non-US requests return {status: "out_of_region_waitlist"} — not an error;
the request is logged for geographic expansion planning.

## Full Documentation

- [llms-full.txt](https://sunrays.dev/llms-full.txt) — Complete tool schemas, all error codes, identity layer spec, spending cap format, state machine, pricing engine detail.

## Contact

- Email: help@sunrays.dev
- MCP: https://mcp.sunrays.dev/mcp
- Well-known: https://sunrays.dev/.well-known/mcp.json