# AI agent integration (MCP)

The Distribution Partner API exposes a **Model Context Protocol (MCP)** server so an AI agent can discover and read inventory as native tool calls. The MCP server is a thin façade over the same canonical `/api/v1/*` contract documented in the [API reference](/developer/api-reference.md); it owns no separate business logic and no separate pricing or usage rules. Anything an agent does through a tool behaves exactly as the equivalent 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 authenticates exactly as a REST client does: it carries the partner's **OAuth 2.0 Bearer token** (`Authorization: Bearer <token>`) obtained from the client-credentials flow. The token's tenant and scope claims are forwarded unchanged on every tool call. See [Authentication](/developer/authentication.md) for how to obtain the token.

## Tool catalogue

Each tool maps directly onto a canonical read operation. Inputs and outputs derive from the same request/response schemas as the REST endpoints, so the [API reference](/developer/api-reference.md) is the single source of truth for tool parameters. The current tool set is:

| Tool                 | Maps to                                         | Scope                  | Purpose                                                                                        |
| -------------------- | ----------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
| `search`             | `POST /search`                                  | `distribution:read`    | Batch availability — ranked allocations for properties, dates, and occupancy.                  |
| `list_properties`    | `GET /properties`                               | `distribution:read`    | Paginated content feed with an optional `updated_since` delta cursor for incremental sync.     |
| `get_property`       | `GET /properties/{public_id}`                   | `distribution:read`    | Full property content document, locale-resolved.                                               |
| `prebook`            | `POST /prebook`                                 | `distribution:booking` | Re-price and hold an offer; returns 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.                    |
| `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.          |

Read tools require `distribution:read`; booking tools require `distribution:booking`. A tool call carrying a token that lacks the required scope is rejected the same way the REST surface rejects it (insufficient scope). Grant only the scopes an agent needs.

## A typical agent flow

1. `list_properties` / `get_property` — build context about the catalogue.
2. `search` — get ranked allocations for the requested dates and occupancy; pick a `rate_key` from an allocation.
3. `prebook` — re-price and hold the offer; read back the match status and cancellation policy, then confirm with the user.
4. `book` — finalize with guest and contact details and a unique `idempotency_key`.
5. `get_booking` — poll until a terminal status if the booking came back pending.
6. `cancellation_quote` → `cancel` — preview the fee, then cancel if the user confirms.

Each tool behaves exactly as the equivalent REST call documented in [The booking flow](/developer/booking-flow.md); the [API reference](/developer/api-reference.md) is the single source of truth for every tool's parameters.

## Consuming the contract directly

An agent that prefers to call the REST surface directly can self-serve 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: 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:

```
GET https://adrasis.gitbook.io/developer/ai-agents-mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.