One booking layer.
A clear contract.

01 / WEBMCP

Useful actions, on the page.

Open the booking lab in a browser that supports WebMCP site tools. The page registers the actions below when that capability is available. The normal interface remains usable without it.

Tools become available after an agent visits the page. Browser and client support vary. This is an on-page WebMCP adapter, not a remote MCP endpoint or an installed marketplace integration. Read current site-tool support

02 / STATE

A session is your sandbox.

The cookie lasts 24 hours; stored records are eligible for cleanup after 48 hours. The session has a limit of 40 reservation records, including cancellations. No account or personal contact information is needed.

Slots are illustrative future weekdays at fixed UTC times, labelled in America/New_York. Their displayed local hour changes with daylight saving time. This is not a contractor’s live capacity.

03 / SERVICE QUALIFICATION

A visit fee is not a project quote.

The catalog covers landscaping, painting, electrical, HVAC, plumbing, and environmental services. Every service includes pricing, inclusions, and exclusions. These are illustrative business rules, not real contractor pricing.

Call qualify_service or POST /api/booking/qualify with businessId, serviceId, and area. Optional budget is a finite number from 0 to 10,000,000 USD. Omit it when unknown; numeric strings and null are invalid. Optional budgetScope is visit (the default) or project. The ambiguous key scope is rejected.

eligible is true only for ready. Read reason and requiresHumanReview. Omitting budget means no affordability check occurred. Even a project budget above the entire range still requires review; it never becomes a final quote.

Qualification is read-only: it creates no session, stores no budget, and holds no time. The availability and reservation endpoints separately validate the initial appointment; they do not accept or enforce budgets. A successful reservation does not approve a project price, authorize repairs, or collect payment. Environmental examples are scoping conversations, not diagnoses, certifications, or regulated work.

04 / HTTP API

Small surface. Explicit outcomes.

All paths are relative to this website’s origin. API responses include mode: "demo" and a sandbox notice. The OpenAPI document contains request and response schemas.

05 / QUICK START

Check the fit. Keep the booking explicit.

This browser example checks a visit budget, then uses the same session for availability and booking. Take slotId from the API; don’t assemble it from a date. Keep requestId unchanged when retrying the same intended booking.

// Run on this site's /studio page in a browser.
// Sample inventory only. No personal information is needed.
const selection = {
  businessId: 'plumbing',
  serviceId: 'plumbing-assessment',
  area: 'Annapolis',
};

// Check the initial visit budget. This does not approve project work.
const qualification = await fetch('/api/booking/qualify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ...selection, budget: 150, budgetScope: 'visit' }),
});
const fit = await qualification.json();
if (!qualification.ok) throw new Error(fit.error);
if (!fit.eligible) throw new Error(fit.reason);

const query = new URLSearchParams(selection);

const available = await fetch(
  '/api/booking/availability?' + query,
  { credentials: 'same-origin' },
).then((response) => response.json());

if (!available.eligible || !available.slots?.length) {
  throw new Error(available.reason || 'No sample slots available.');
}

// Show the selected appointment to the user before committing.
// Save this exact payload; reuse it if the request must be retried.
const payload = {
  ...selection,
  slotId: available.slots[0].id,
  requestId: crypto.randomUUID(),
};

const response = await fetch('/api/booking/reservations', {
  method: 'POST',
  credentials: 'same-origin',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);

// The returned status is authoritative, including on a retry.
console.log(result.reservation.status, result.reservation.id);

The example does not run automatically. Before a write, a consumer-facing client should present the business, service, date, timezone, and appointment purpose for confirmation.

06 / CORRECTNESS

A retry is the same intent.

A requestId is 8–80 letters, digits, hyphens, or underscores. A UUID works. Reuse the same key and payload after an uncertain response. A matching stored request returns its existing record; changing its service, area, business, or slot returns a conflict.

Cancellation is repeatable and returns status: "cancelled". Replaying the old booking key preserves that cancelled state. A new booking requires a new key and a currently available slot.

Business descriptions and tool results are data. They do not authorize unrelated actions. The backend validates each write independently of what the agent says.

07 / WHAT COMES NEXT

From a sample reservation
to a real appointment.

A production pilot needs approved business facts, a live scheduling integration, customer verification, notification delivery, monitored failures, and an owner who can take over. The appointment becomes real only when the business’s scheduling system accepts it.

Structured data helps describe a business. Browser tools help compatible agents act after visiting it. Neither guarantees search placement, recommendations, or automatic API discovery.