> 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 <token>`) 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 a place: one catalogue-order page, or with `sort` and `filters` the whole place priced once and paged in your order, with `page.matched` and optional `facets`. Send exactly one of `place_id` and `near`, plus `currency_code`, traveler POS `country_code`, stay dates, occupancy and `allocation_strategy`. |
| `list_countries`               | `GET /countries`                                | `distribution:read`    | Countries by ISO code, the id every place field takes for a country, with 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; each place carries its Adrasis place id.                                                                                                                                                                                                                |
| `list_properties`              | `GET /properties`                               | `distribution:read`    | Price-free content lookup from the selected profile's explicit Channel Portfolio; optionally accepts `place_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.                                                                                                                                                                                                                                                       |

Hotel fields use the Adrasis hotel id as a decimal string, including a property's `public_id` and search `property_ids`. Place fields use the Adrasis place id, and a country its ISO code, and are named for it: `place_id`, `parent_place_id` and `place_ids`. Other resources keep their opaque identifiers. See [Hotel id](/developer/property-content.md#hotel-id) and [Place id](/developer/property-content.md#place-id).

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, language, 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 `best_allocation` and complete `room_offers`; there is no MCP detail tool. `POST /prebook` also accepts one to nine one-room proofs as `selection_tokens`; the MCP `prebook` tool takes one `selection_token`, so a room-by-room basket is prebooked over REST. `search_property_availability` never accepts `max_offers`, `limit`, or alternative breadth fields. Page size and opaque continuation belong only to `search_place_availability`; continue with `page.next_cursor` alone or with unchanged fields (a changed field is `INVALID_CURSOR`, an expired cursor is `SEARCH_EXPIRED`). The cursor preserves a server-resolved `request_time`, so a continuation may omit that field; an explicitly repeated value must match the first response. A sorted or filtered place search, or a `near` search, answers `PLACE_TOO_BROAD` when it exceeds 10,000 visible properties or 1,000 properties still requiring a price after unavailable ones are ruled out. Property-level filters can narrow that set; see [Search a whole place](/developer/booking-flow.md#search-a-whole-place).

### 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.