> For the complete documentation index, see [llms.txt](https://adrasis.gitbook.io/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adrasis.gitbook.io/developer/ai-agents-mcp.md). # AI agent integration (MCP) Use the Distribution Partner API as Model Context Protocol (MCP) tools backed by the REST contract. The Distribution Partner API exposes a **Model Context Protocol (MCP)** server for AI agents. It wraps the `/api/v1/*` REST contract documented in the [API reference](/developer/api-reference.md) and uses the same schemas, business logic, pricing, and usage rules. Each tool behaves like the corresponding REST call. ## Transport & auth The server is a remote MCP server reachable over streamable HTTP at: ``` https://ari.console.adrasis.com/mcp ``` An agent session uses the same authentication as a REST client: it carries the partner's **OAuth 2.0 Bearer token** (`Authorization: Bearer `) obtained from the client-credentials flow. The authenticated partner account and scope claims are forwarded unchanged on every tool call. See [Authentication](/developer/authentication.md) for how to obtain the token. Profile-scoped tools accept an optional MCP-only `profile_public_id` field. Omit it to use the account's stable Default profile; provide it to select another profile owned by the same account. The facade sends this value as the REST profile-selector header, never in the REST JSON body. A successful structured tool result includes the exact resolved `profile_public_id` beside the REST response. ## Tool catalogue Each tool maps to a REST operation and uses the same request and response schemas. See the [API reference](/developer/api-reference.md) for its parameters. ### Accommodation | Tool | Maps to | Scope | Purpose | | ------------------------------ | ----------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_property_availability` | `POST /properties/availability` | `distribution:read` | Exact top-1 availability for each of 1..100 unique properties; requires `country_code` and `allocation_strategy` (`strict` or `flexible`). | | `search_place_availability` | `POST /places/availability` | `distribution:read` | Exact top-1 availability for one access-visible place candidate page; requires `place_public_id`, `currency_code`, and traveler POS `country_code`. | | `list_countries` | `GET /countries` | `distribution:read` | Canonical country public IDs, ISO codes, and localized names. | | `list_place_types` | `GET /reference/place-types` | `distribution:read` | All eight place types with country-specific `available` and `searchable` flags. | | `list_places` | `GET /places` | `distribution:read` | Canonical destination hierarchy by country, type, parent, or localized-name search. | | `list_properties` | `GET /properties` | `distribution:read` | Price-free content lookup from the selected profile's explicit Channel Portfolio; optionally accepts `place_public_id` and never takes point of sale. | | `get_property` | `GET /properties/{public_id}` | `distribution:read` | Full property content from the same profile-scoped Channel Portfolio. | | `prebook` | `POST /prebook` | `distribution:booking` | Re-price the exact slots sealed by `selection_token` and return a `prebook_token`, match status, and policy snapshot. | | `book` | `POST /book` | `distribution:booking` | Finalize a reservation from a `prebook_token`; requires an `idempotency_key` for safe retries. | | `get_booking` | `GET /bookings/{public_id}` | `distribution:booking` | Read a booking by `public_id`; also the poll tool for pending reservations. | | `list_bookings` | `GET /bookings` | `distribution:booking` | Account-wide, PII-free reconciliation by exact `agency_reference`, bounded creation/check-in window, or `updated_since`, with opaque cursors and an optional originating-profile filter. | | `cancellation_quote` | `POST /bookings/{public_id}/cancellation-quote` | `distribution:booking` | Preview the cancellation fee with no side effects. | | `cancel` | `POST /bookings/{public_id}/cancel` | `distribution:booking` | Cancel a booking and realise the penalty; idempotent on an already-cancelled booking. | The property metadata catalogue contains only published accommodation properties explicitly opened in the selected profile's Channel Portfolio. Enrollment, source market, destination rules, rates, inventory, and availability neither expand nor narrow `list_properties` or `get_property`; only the availability tools take traveler point of sale and decide sellability. Property-list continuations are POS-free cursors bound to the partner account, resolved profile, place, locale, delta filter, and profile catalogue revision. `profile_public_id` has different semantics on `list_bookings`: it is an optional account-wide reporting filter for the immutable profile that originated each booking. It does not select a catalogue for that read, and it can identify a profile disabled after the booking was created. The single-property `POST /properties/{property_public_id}/offers/search` route is REST-only in this contract. It returns at most twenty allocations plus `has_more`; there is no MCP detail tool. `search_property_availability` never accepts `max_offers`, `limit`, or alternative breadth fields. Candidate breadth and opaque continuation belong only to `search_place_availability`; repeat all filters with `page.next_cursor`. The cursor preserves a server-resolved `request_time`, so a continuation may omit that field; an explicitly repeated value must match the first response. ### Transfer, tour & flight Every vertical operation follows the same `search → prebook → book` shape as accommodation, and each requires `distribution:booking`. | Tool | Maps to | Scope | Purpose | | ------------------ | ------------------------ | ---------------------- | --------------------------------------------------------------------------------- | | `search_transfers` | `POST /transfer/search` | `distribution:booking` | Search transfer offers between two zones for a service date and party. | | `prebook_transfer` | `POST /transfer/prebook` | `distribution:booking` | Re-price a transfer offer and return a `prebook_token` and cancellation snapshot. | | `book_transfer` | `POST /transfer/book` | `distribution:booking` | Finalize a transfer from a `prebook_token`; requires an `idempotency_key`. | | `search_tours` | `POST /tour/search` | `distribution:booking` | Search tour offers for a tour/modality on a departure date and party. | | `prebook_tour` | `POST /tour/prebook` | `distribution:booking` | Re-price a tour offer and return a `prebook_token` and cancellation snapshot. | | `book_tour` | `POST /tour/book` | `distribution:booking` | Finalize a tour from a `prebook_token`; requires an `idempotency_key`. | | `search_flights` | `POST /flight/search` | `distribution:booking` | Search charter flight offers for a departure date and pax mix. | | `prebook_flight` | `POST /flight/prebook` | `distribution:booking` | Re-price a flight offer and return a `prebook_token` and cancellation snapshot. | | `book_flight` | `POST /flight/book` | `distribution:booking` | Finalize a flight from a `prebook_token`; requires an `idempotency_key`. | ### Packages An atomic package is composed, revalidated and finalized through its own three tools; it is then read and cancelled with the `get_booking`, `cancellation_quote` and `cancel` tools listed above. Those last two accept an optional `item_public_ids` array to target individual package services instead of the whole booking. | Tool | Maps to | Scope | Purpose | | ----------------- | ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_packages` | `POST /package/search` | `distribution:booking` | Compose 2-5 already-selected component allocations spanning at least two product types into one inclusive-price offer; returns a `package_allocation_id` valid 15 minutes. | | `prebook_package` | `POST /package/prebook` | `distribution:booking` | Re-evaluate every component of a stored package offer; returns the match status, the compliance disclosure, and a `prebook_token` valid 30 minutes. | | `book_package` | `POST /package/book` | `distribution:booking` | Atomically finalize the package from a `prebook_token`; requires an `idempotency_key`. | ### Trip grouping | Tool | Maps to | Scope | Purpose | | -------------------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create_trip` | `POST /trip` | `distribution:booking` | Group bookings that are already confirmed into one money-free trip. The `link_type` records the regulatory relationship only; it does not create an atomic package. | | `get_trip` | `GET /trip/{public_id}` | `distribution:booking` | Read a trip, including members and per-currency combined totals. | | `add_trip_member` | `POST /trip/{public_id}/members` | `distribution:booking` | Add an existing booking to a trip. | | `remove_trip_member` | `DELETE /trip/{public_id}/members/{booking_public_id}` | `distribution:booking` | Remove a booking from a trip. | | `cancel_trip` | `POST /trip/{public_id}/cancel` | `distribution:booking` | Cancel every member booking of a trip; returns a per-member outcome list. | Read tools require `distribution:read`; booking and vertical tools require `distribution:booking`. A tool call without the required scope is rejected for insufficient scope. Grant only the scopes an agent needs. ## A typical agent flow 1. `list_countries` → `list_place_types` → `list_places`: Resolve canonical geography and searchable place kinds. 2. `list_properties` / `get_property`: Build price-free context from the selected profile's Channel Portfolio without a point-of-sale input. 3. `search_property_availability`, or `search_place_availability` when walking a geography: request exact top-1 winners with explicit `strict` or `flexible` allocation intent; choose a returned allocation and keep its opaque `selection_token` server-side. 4. `prebook`: Pass that `selection_token` to re-price the sealed slots and mint a token. Read the match status and cancellation policy, then confirm with the user. Inventory remains unheld until `book`. 5. `book`: Finalize with guest and contact details and a unique `idempotency_key`. 6. `get_booking`: Poll until a terminal status if the booking came back pending. 7. `list_bookings`: Reconcile account-wide by the caller's exact `agency_reference` or a bounded date/delta window; add `profile_public_id` only to narrow reporting to one originating profile. 8. `cancellation_quote` → `cancel`: Preview the fee, then cancel if the user confirms. ## Consuming the contract directly An agent can also call the REST surface directly from the published contract: * The published site serves an LLM-readable index of this portal as plain text at `/llms.txt`. * The full machine-readable contract is rendered on the [API reference](/developer/api-reference.md) page. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://adrasis.gitbook.io/developer/ai-agents-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.