MCP

Appearance

Data Types ​

Reference for all data structures returned by the MCP tools.

Hotel ​

The core hotel object returned in every search/fetch response.

typescript
{
  id: string                    // Unique hotel identifier
  name: string                  // Hotel display name
  url: string                   // Direct Vio booking page URL
  propertyDescription?: string  // Hotel description
  roomsDescription?: string     // Rooms overview text
  phone?: string                // Contact number
  isPartialMatch?: boolean      // True if hotel matches only SOME filters (see below)
  isAnchorHotel?: boolean       // True for the anchor hotel in similarity search
  typicalPriceRange?: {         // Historical price range
    min: number
    max: number
  }
}

isPartialMatch ​

When filters are applied, the server returns the best matches first. If there aren't enough hotels matching all filters, additional hotels that match only some filters are included with isPartialMatch: true. Hotels without this flag (or with false) match all requested filters exactly.

Use this to visually distinguish partial matches in your UI — for example, showing a note like "doesn't match all your filters" or ranking them below exact matches.

Location ​

Included when include contains "location".

typescript
{
  address: string               // Full address
  displayName: string           // City/area name
  latitude: number | null
  longitude: number | null
  timezone?: string             // IANA timezone
  areaDescription?: string      // Description of the surrounding area
  attractionsDescription?: string
  nearbyAttractions?: [{
    name: string
    distanceKm: number
    distanceMiles: number
  }]
}

Rating ​

Included when include contains "rating".

typescript
{
  overall: number               // 0-10 scale
  reviewCount: number | null
  guestType?: {                 // Ratings by guest type
    business?: number
    couples?: number
    families?: number
    groups?: number
    solo?: number
  }
  detailed?: {                  // Category breakdown
    cleanliness?: number
    dining?: number
    facilities?: number
    location?: number
    pricing?: number
    rooms?: number
    service?: number
  }
}

Classification ​

Included when include contains "classification".

typescript
{
  starRating: number | null     // 0-5 scale
  propertyType?: {
    id: string
    name: string                // "Hotel", "Apartment", "Resort", etc.
  }
  themes?: [{id: string, name: string}]
  sentiments?: [{id: string, name: string}]
  nationalRatingsDescription?: string
}

Facilities ​

Included when include contains "facility".

typescript
{
  items: [{
    id: string
    name: string                // Localized facility name
  }]
  amenities?: string            // General amenities text
  business?: string             // Business facilities text
  dining?: string               // Dining facilities text
}

Media ​

Included when include contains "media".

typescript
{
  images: string[]              // CDN-optimized image URLs (WebP)
  imagesAvailable: number       // Total images available
}

Offers ​

Included when include contains "offer". The contents depend on offers.mode:

  • top_offers (default) and cheapest return a curated selection in ranking order.
  • all returns the hotel's room inventory rates, cheapest first (sorted by rate.displayPrice ascending); every offer carries its room via roomId/roomName, and cheapestRate always equals the first item's rate. Pair all with searchMode: "deep" when completeness matters — fast mode may return a partial inventory, reported by roomsComplete: false on the response.
typescript
{
  items: [{
    id: string
    url: string                 // Direct booking URL
    currency: string            // ISO 4217
    rate: {
      base?: number             // Room rate
      taxes?: number            // Tax amount
      hotelFees?: number        // Additional fees
      displayPrice?: number     // The price to display (total incl. fees, excl. taxes where applicable)
    }
    cancellationPenalties?: [{
      amount?: number
      currency?: string
      start?: string            // ISO date
      end?: string
    }]
    package?: {
      amenities?: string[]      // e.g., ["Breakfast included"]
    }
    // package and occupancy may be omitted on some offers: absence means
    // unknown, not "not included".
    availableRooms?: number
    providerCode?: string       // e.g., "booking.com"
    providerName?: string       // e.g., "Booking.com"
    roomId?: string
    roomName?: string
    tags?: string[]             // Special feature/pricing tags (see Offer Tags below)
    occupancy?: {
      adults: number
      children?: number[]       // Ages
    }
  }]
  availableCount?: number       // Count of the returned offer list
  cheapestRate?: {              // Always the cheapest of the returned list
    base?: number
    taxes?: number
    hotelFees?: number
    displayPrice?: number
  }
}

The summary fields always describe the returned list: they never disagree with items. anchorRate and roomsReference appear in the curated modes only. The curated modes (top_offers, cheapest) and the all list are sourced independently and can diverge: a curated price may differ slightly from the all list's price for the same room and conditions.

Offer tags ​

The tags array indicates special features or pricing positions for an offer:

TagDescription
cheapest_offerThe cheapest available offer for this hotel
top_offerA top-rated offer based on value and quality
exclusiveAn exclusive offer only available through Vio
exclusive_cheapest_offerThe cheapest offer and exclusive to Vio
anchor_priceThe reference price from the anchor hotel in similarity searches
price_dropPrice has recently dropped compared to historical rates
preferred_rateA preferred/negotiated rate
charge_laterPay at the hotel, no upfront charge required
deal_freezePrice has been frozen/locked for a limited time

Use these tags to highlight deals, show badges, or prioritize offers in your UI.

Rooms ​

Included when include contains "room".

typescript
{
  id: string
  name: string
  description?: string
  maxOccupancy?: number
  amenities?: string[]          // e.g., ["Air conditioning", "Mini bar"]
  bedTypes?: [{
    id?: string
    name?: string               // e.g., "King bed", "Twin beds"
  }]
  images?: string[]             // Room-specific images
  area?: {
    squareMeters?: number
    squareFeet?: number
  }
  smokingOptionsAvailable?: boolean
}

Rooms describe the property's room types: they carry no rates. Every bookable rate lives in offers.items; use the offer's roomId/roomName to show rates per room (request offers.mode: "all" for the full rate list).

Reviews ​

Included when include contains "review".

typescript
{
  totalAvailable: number
  averageRating: number | null
  perRatingBreakdown: {         // Count per rating score
    [rating: string]: number
  }
  items: [{
    date?: string               // ISO date
    name?: string               // Reviewer name
    score?: number              // 1-10
    text?: string               // Review text
    language?: string           // ISO 639-1
    source?: string             // Review source
    checkIn?: string
    checkOut?: string
  }]
}

Insights ​

Included when include contains "insight". AI-generated review summaries.

typescript
{
  overall: string               // Overall AI summary
  categories: [{
    category: string            // "Facilities", "Cleanliness", "Rooms",
                                // "Service", "Location", "Food"
    title: string               // Short title
    summary: string             // Category-specific summary
  }]
}

Analytics ​

Included when include contains "analytic". Price intelligence data.

typescript
{
  averagePrice?: number
  timeRangeDays?: number
  comparisonToSimilar?: {
    differencePercentage: number // Negative = cheaper than similar
    assessment: "cheaper" | "same" | "expensive"
  }
  history?: [{
    timestamp: string
    price: number
  }]
  similarHotelsHistory?: [{
    timestamp: string
    price: number
  }]
}

Policies ​

Included when include contains "policy".

typescript
{
  checkIn?: {
    beginTime?: string
    endTime?: string
    minAge?: number
    instructions?: string
    specialInstructions?: string
  }
  checkOut?: {
    time?: string
  }
  fees?: {
    mandatory?: string
    optional?: string
  }
  feesDescription?: string
  policiesDescription?: string
  knowBeforeYouGo?: string
  deposit?: {
    amount?: number
    currency?: string
    description?: string
  }
  generalPolicies?: string
}

FAQ ​

Included when include contains "faq".

typescript
{
  question: string
  answer: string
  label?: string                // Category label
}

Availability entry ​

Returned by search_hotels_availability.

typescript
{
  hotelId: string
  checkIn: string               // ISO date
  cheapestRate?: {
    base?: number
    taxes?: number
    hotelFees?: number
    displayPrice?: number       // Tax/fee-inclusive price per the user's country
  }
  offerCount?: number           // Number of available offers
}