Integrate REST API & MCP.

Connect MCP

1. Add a remote server in your MCP client.
2. Connect the following URL using Streamable HTTP. No credentials are required.
3. List the tools and start with get_service_options.

https://platform-api.samuelz.com/api/v1/mcp/chauffeur/samuelz-chauffeur

Use REST for browser applications. The MCP endpoint accepts browser origins only from approved domains.

View Samuelz in the official MCP Registry ↗

Info2 reads information. Quote3 adds anonymous price previews. Only Full5 can prepare an explicitly requested unpaid offer.

Generated profile, field and response schemas ↗

Use the REST API

Safe first step: read services and preparation policy. These GET requests calculate no price and need no customer data; the shared pilot limit still applies.

https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur

curl --fail-with-body "https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/services?locale=en"
curl --fail-with-body "https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/policy?locale=en"

Request a price preview

JavaScript example with a synthetic route and a date seven days ahead. Running it calls the real, limited price API; this is not a sandbox. Nothing runs automatically on this page.

const date = new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10);
const input = {
  "locale": "en",
  "ride": {
    "pickup": "Munich Airport (MUC)",
    "destination": "Marienplatz 1, München",
    "date": date,
    "time": "10:30",
    "passengers": 2,
    "tripType": "one_way"
  }
};
const response = await fetch("https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/quotes", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(input),
  signal: AbortSignal.timeout(20000)
});
const result = await response.json();
console.log(response.status, response.headers.get("Retry-After"), result);

Date and time use the service time zone returned by /services. Return trips require tripType: "return", returnDate and returnTime after the outbound ride. Do not include customer names or contact details.

Always inspect status. For quoted results, quote contains integer-cent amounts with a currency. revalidationRequired: true means the price and offer must be checked again before booking. A preview does not reserve a vehicle.

Prepare a binding offer

Call prepare_offer only after the customer explicitly requests an offer. It requires offerRequested: true, a UUID submissionId, a random 64-character hexadecimal resumeToken and an email or E.164 mobile number. Older clients without offerRequested are safely rejected. Store both values securely. Approved pilot partners may also send their distributionPartnerCapability. Replays with the same values return the same offer; changes require a new ID and capability; get_offer_status only reads that operation. prepared does not dispatch a chauffeur or charge a payment.

const date = new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10);
const submissionId = crypto.randomUUID();
const resumeToken = Array.from(crypto.getRandomValues(new Uint8Array(32)),
  byte => byte.toString(16).padStart(2, "0")).join("");
const input = { ...{
    "locale": "en",
    "ride": {
      "pickup": "Munich Airport (MUC)",
      "destination": "Marienplatz 1, München",
      "date": date,
      "time": "10:30",
      "passengers": 2,
      "tripType": "one_way"
    }
  },
// Only after the customer explicitly requests an offer.
  submissionId, resumeToken, offerRequested: true,
  contact: { email: "REPLACE ME" } };
const response = await fetch("https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/offers/prepare", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify(input)
});
console.log(response.status, await response.json());

A prepared offer binds price, expiry, route and the applicable cancellation, waiting, service and legal terms. checkoutUrl and termsUrl lead to the same revision-bound customer decision. Only explicit consent there can confirm the booking; the API does not accept payment.

The resume capability lasts 24 hours; offer expiry is separately stated in offer.expiresAt. not_found may mean a missing, wrong or expired capability and does not prove that no offer was created. For pending, respect retryAfterSeconds and read the same operation. Do not automatically create a new offer after ambiguous/conflict. unavailable is not a payment status; paid, cancelled or deleted offers may return it.

Handle limits and errors

The pilot has a limited request allowance shared across both channels. For a larger integration, we will agree capacity and workflow together.

REST and MCP share provider and client limits. Switching channels does not increase the allowance. Avoid automatic retry loops; a timed-out call may already count.

Booking and terms

A prepared offer binds price, expiry, route and the applicable cancellation, waiting, service and legal terms. checkoutUrl and termsUrl lead to the same revision-bound customer decision. Only explicit consent there can confirm the booking; the API does not accept payment.

Your system reads current information and obtains a price preview. The returned booking link lets the customer review the current offer, applicable terms and payment.

No commission rate, settlement timing or SLA is published. For each partner, agree compensation and settlement, cancellations/refunds, roles and data handling, access allowance, and support before the pilot starts. The customer confirms ride terms in Samuelz checkout.

Version, status and support

Public REST API v1 (OpenAPI information version 1.0.0). MCP contracts: Full5 2.2.0 (5 Tools), Quote3 1.3.0 (3 Tools), Info2 1.1.0 (2 Tools). The OpenAPI contract and MCP tool schemas define the generated reference. Prices and policies come from the current provider policy.

This pilot publishes no public availability feed or uptime commitment. For technical questions, email support@samuelz.com; do not include passenger data, access codes or tokens.