Order Labs (MCP)
Full purchase-to-results flow via MCP tools.
Step 1 — ensure profile is complete
Lab orders need: gender, phone (with dial code), birth date, and complete home address.
getProfile()— check fields. AnythingN/Ablocks the order.- If missing, call
updateProfile(...)to fill them. Phone requires bothphoneandphoneDialCode.
The home address must be the user's personal home address. Never use a lab service center, appointment location, or anything from searchLabServiceCenters.
Step 2 — browse and select
listAvailableLabTests requires confirmedUsState and fails closed without it (returns locationRequired: true). Confirm the state with the user first — never guess. Same-named panels can be different sellable products across states, so always reference labs by objectKey, never by display name.
listAvailableLabTests(confirmedUsState)— show name, price, included biomarkers, andobjectKey- Confirm the user wants to proceed before any payment
Step 3 — pay
An app connected by signing in (Claude, ChatGPT) skips to If no saved cards: it gets only the checkout link.
listSavedPaymentMethods()— check for saved cards
If saved cards exist:
- Show available cards (brand, last 4) and ask which to use
purchaseLabTest(labTestObjectKey, paymentMethodExternalId)— nothing is charged yet: returns a preview (test, price, discount, card) and apendingId- Show the preview. Only after the user says yes:
confirm_action(pendingId)— charges the card and creates the order
If no saved cards:
purchaseLabTestWithCheckout(labTestObjectKey, successUrl, cancelUrl)— generate Stripe Checkout link- Share the complete
checkoutUrlwith the user (never truncate). Order is created via webhook after payment.
Step 4 — initialize if needed
If auto-init didn't complete (e.g. profile field was missing at purchase time):
getUserLabRecords()— check status- If status is "Paid":
initializeLabOrder(labOrderExternalId)returns a preview (the test and the personal details the lab receives) and apendingId; after the user approves,confirm_action(pendingId)sends it. Requires complete profile.
Step 5 — schedule blood draw
- Ask the user for ZIP code (or use home address)
searchLabServiceCenters(zipCode, labOrderExternalId)— show nearby labs- User picks a lab → ask for date / time preference
getServiceCenterSlots(siteCode, labOrderExternalId, timezone, startDate, rangeDays)— show options. Let the user choose — don't pick automatically.- User picks a slot →
bookLabAppointment(labOrderExternalId, bookingKey, timezone)returns a preview (test, date, time, place) and apendingId. AbookingKeyis valid for 30 minutes. - Only after the user says yes:
confirm_action(pendingId)books it
Step 6 — manage appointment
- Reschedule (only while status is "Appointment Scheduled"):
getServiceCenterSlotsfor new options →rescheduleLabAppointment(labOrderExternalId, newBookingKey, timezone)returns a preview of the current and the new appointment →confirm_action(pendingId)after the user says yes. The old appointment is cancelled. - Cancel: call
cancelLabAppointment(labOrderExternalId)without a reason → show the reasons → call again with the chosenreasonIdfor a preview →confirm_action(pendingId)after the user says yes - Re-book after cancel: use
bookLabAppointment(notrescheduleLabAppointment— reschedule only works on active appointments)
Step 7 — view results
After the user visits the lab, results process automatically. Once status reaches "Completed":
searchBiomarkers— view values and rangesgetBiologicalAge()— see how it shifts the user's biological age
Status reference
| Status | Next step |
|---|---|
| Paid | Complete profile, then initializeLabOrder |
| Order Submitted | Wait — no action needed |
| Requisition Created | Search for labs and book |
| Appointment Scheduled | Visit at the scheduled time. Can reschedule/cancel. |
| Appointment Cancelled | bookLabAppointment for a new appointment |
| Redraw Available | Schedule a new appointment for the redraw |
| Partial Results | View available, wait for the rest |
| Completed | View with searchBiomarkers and getBiologicalAge |
| Failed | Contact support or reorder |
Every order from getUserLabRecords includes statusDescription and nextStep fields. Use nextStep as your primary guide. get_updates reports orders whose status changed since the last call.
If confirm_action answers stale
The price or the appointment changed after the preview. Prepare the action again and show the new preview. See Confirming actions.

