Dreamfare MCP tool reference
42 tools at https://api.dreamfare.app/mcp, grouped by capability. Names, titles and descriptions are exactly what an agent receives from tools/list; the badge is the tool's own annotation (read-only, writes, or writes that can remove or overwrite something).
Trip creation and editing
Create a trip from a day-by-day plan, read it back with stop ids, edit anything in one batched call, copy or delete it, and keep the packing list.
create_tripCreate a Dreamfare tripWrites- Save a travel plan as a Dreamfare trip the traveler can open, edit with their crew, and book. Pass the full day-by-day plan in one call via `days`. Stops are enriched shortly after creation (photos, map pins, booking links), so re-read with get_trip if the traveler asks to book. Before creating a plan for a destination, check list_saved_places for the traveler's saves there (they needn't mention them) and ask whether to include them — add_saved_places_to_trip carries them over with pins and links. Returns the trip and its URL — always give the traveler that URL.
get_tripRead a tripRead-only- Read one Dreamfare trip: days, stops (with stopIds for edit_trip), the packing list, and per-stop booking links. When the traveler wants to book a stop, give them its bookingUrl — bookings through it earn them commission back.
list_tripsList the traveler's tripsRead-only- List the traveler's Dreamfare trips (own and shared), newest first — a lookup for trip ids. To show a trip, follow with get_trip, which renders the trip card.
edit_tripEdit a tripWrites, may be destructive- Edit anything on a trip in one batched call: trip details and notes (update_trip), stops (update_stop / remove_stop / move_stop, by stopId from get_trip), days (add_day / update_day / remove_day, by 0-based dayIndex), and the planning stage (finalize locks the trip for sharing and booking; reopen unlocks it). Omitted fields keep their value; null clears. finalize/reopen run AFTER the other actions — a finalized trip rejects edits, so reopen it in its own call first.
add_stopsAdd stops to a tripWrites- Add stops (places, activities, meals, stays, transport) to an existing Dreamfare trip. dayIndex is 0-based; read the trip first with get_trip if unsure of its days.
add_option_to_tripAttach a searched option to a tripWrites- Attach one search result to a trip as a stop: kind 'stay' / 'activity' takes the option/offer object from the matching search tool; kind 'place' takes a search_places result's itemDraft. Echo objects exactly as returned. Stays need checkIn/checkOut. Say which day with dayIndex or date (a stay defaults to its check-in date) and, when the traveler has one in mind, the start time. The stop's bookingUrl (in this result and get_trip) is the link to present for booking.
copy_tripCopy a trip into the traveler's accountWrites- Make the traveler their own editable copy of a trip: a published one (publicationId from explore_trips — keeps the creator's attribution and re-bases flights on the traveler's home airport) or one of their own trips (tripId — dates, stops and the shared packing list come along). Returns the new trip.
delete_tripDelete a tripWrites, may be destructive- Delete a trip the traveler owns (also unpublishes it from Explore). Requires echoing the exact trip title as confirmTitle — only call this after the traveler explicitly asks to delete the trip.
manage_packingEdit a trip's packing listWrites, may be destructive- Add, check off, uncheck, or remove packing-list items on a trip. Item ids come from get_trip's packing array (or this tool's response). Personal items are visible only to this traveler; shared items belong to the whole crew.
mark_stop_bookedMark a stop as bookedWrites- Record that the traveler completed a booking for a stop (on the partner site or elsewhere). When they booked through the stop's tracked bookingUrl this also opens the commission credit that pays their share back once the partner reports it.
AI itinerary planning
Build a complete trip in one call with Dreamfare's own planner: real venues with opening hours, a stay, partner activities, and booking links.
plan_tripPlan a whole trip with Dreamfare's plannerWrites, may be destructiveReaches partners- Build a complete day-by-day trip in one call using Dreamfare's own planner: real venues (with opening hours), a stay, activities from partner inventory, the traveler's saved places woven in, pins, photos and booking links — all server-side, in about 10 seconds. Costs Stardust credits like planning in the app (get_profile shows the balance). Prefer this for 'plan me N days in X' requests; use create_trip when the traveler has dictated the exact stops themselves. The traveler's SAVED places at the destination count even when they don't mention them: pass savedPlaceIds/folderName for the ones they want in, or includeSavedPlaces (true = all of them, false = none). Leave all three out and, when they have saves there, the call returns them unbuilt and uncharged so you can ask first. Give the traveler the trip URL.
Place discovery and research
Find real venues for a destination with ratings, pins and photos, then research one option in depth or compare a few side by side.
search_placesDiscover real placesRead-onlyReaches partners- Real venues for a destination — restaurants, activities, hotels, landmarks, shopping — with ratings, pins, and photos (partner inventory + cached Google Places, the app's own Explore surface). Use it to ground a plan in real places. Each result carries an itemDraft: attach one to a trip with add_option_to_trip (kind 'place', echoing the itemDraft unchanged) to keep its pin, photo, and any partner bookability. For hotels pass checkIn/checkOut (or use search_stays): without them prices are for a sample window a month out, and the reply says so in pricedWindow. Hotels added to a day are re-dated to that day and re-quoted automatically. Finer asks: openNow / openAt for 'open now' / 'open Friday at 8pm', priceLevels for '$'–'$$$$' budgets, minRating, near + radiusKm for 'around the cathedral'. A result's placeId (Google places) or itemDraft goes to get_details for hours, summary, reviews, features, photos and — at landmarks — tours and tickets with prices; compare_options weighs 2–5 side by side.
get_detailsResearch one optionRead-onlyReaches partners- Everything known about ONE hotel, tour or place, researched: a photo gallery, what's good about it (editorial summary, what reviewers say), key facts (stars, guest score, capacity, cancellation and instant-book policies; duration, languages, meeting point, inclusions and exclusions, itinerary; opening hours, price level, phone, website), features/amenities, the exact location, and prices — per booking site for hotels, tours & tickets with prices at landmarks. Use it when the traveler asks about a specific option ('tell me more about…', 'is it near…', 'what's included', 'can I cancel', 'is it open Sunday') or before recommending one. Pass the search result object as `option` (or a search_places result's placeId as `id`, or a name + destination when there is no object). Stays: pass checkIn/checkOut/guests so prices are for the traveler's dates. The reply's itemDraft/option go to add_option_to_trip unchanged.
compare_optionsCompare options side by sideRead-onlyReaches partners- Two to five options of one kind (stays, activities or places) in one table: price (per night / per person / total), rating and reviews, distance, duration, stops, cancellation, features — the best cell in each row is marked and `verdict` names the winners (cheapest, best rated, closest, fastest). Each is researched like get_details, so the table is exact, not a summary of the search screen. Use it whenever the traveler is weighing a few ('which of these', 'A or B', 'the cheapest that's still well rated'). Echo the search result objects unchanged in `options`; every column's itemDraft/option goes to add_option_to_trip.
Hotel and stay search
Live stay inventory with all-in prices for a destination and date window, and a re-quote of every partner-priced stay already on a trip.
search_staysSearch places to stayRead-onlyReaches partners- Live hotel/stay inventory with real prices for a destination and date window. Every amount includes taxes and fees; nightly is total ÷ nights, an average that reads higher than the room-only rate booking sites headline. The default order is partner relevance, NOT price: when the traveler wants something cheaper, names a budget, or asks to compare, re-run with maxNightly/minNightly and sort 'cheapest' (or 'rating') instead of repeating the same call — a plain repeat returns the same screen. priceRange summarizes the nightly rates found; each option's suppliers lists every booking site's total for the same room (the option's own price is the cheapest of them). To make an option bookable, attach it to a trip with add_option_to_trip (kind 'stay', echoing the option object unchanged) — the stop then carries the tracked booking link. Finer asks map to filters: 'near the castle' → near, 'well reviewed' → minRating 8, 'free cancellation' → freeCancellation, 'apartment for 4' → minBedrooms, 'family suite' or 'family room' → propertyType 'hotel' + minGuests (never a hostel), 'hostel' → propertyType 'hostel', a hotel the traveler NAMED → name, a STYLE ('ryokan', 'boutique') → keywords. destination is a city or town (a region geocodes to one point). near keeps results within 5 km unless maxDistanceKm says otherwise. To research ONE option (photos, what reviewers say, policies, price on every site) call get_details with it; to weigh a few side by side call compare_options.
refresh_stay_pricesRe-check hotel prices on a tripWritesReaches partners- Re-quote every upcoming partner-priced stay on the trip against live rates and report what moved (previous → current). At most once per stay per day. Returns the refreshed trip.
Activity and tour search
Bookable tours and experiences for a destination, attachable to a trip as a stop.
search_activitiesSearch activities and toursRead-onlyReaches partners- Bookable activities, tours and experiences for a destination. Attach one with add_option_to_trip (kind 'activity'). Plain activity stops added via add_stops also get matched to partners automatically, so search here only when the traveler wants options. Default order is partner relevance: for budget or 'cheaper' asks set maxPrice/minPrice and sort 'cheapest' instead of repeating the search; priceRange summarizes what was found. Say what kind of experience with q ('food tour', 'sunset cruise', 'day trip to Sintra') and narrow with category / flags / duration / minRating. Each result carries tags, flags and a short description; get_details on one returns the full content (inclusions, itinerary, cancellation policy, meeting point, languages, gallery), compare_options weighs 2–5.
Travel video and text import
Turn a TikTok, Instagram, YouTube, Facebook or Reddit link, or pasted notes, into real places with tips, then check the import's results.
import_videoImport places from a video or postWrites, may be destructiveReaches partners- Extract the real places from a TikTok, Instagram, YouTube, Facebook, or Reddit travel link — watched, transcribed, and geocoded. When the traveler shares such a link, call this tool with the URL directly: the DREAMFARE SERVER fetches and watches the video, so never claim you cannot open links or ask for an upload. Runs asynchronously (~30–90s): poll get_import for the results. Found places (with their tips) land in the traveler's saved-places library; once done, drop them into a trip with add_saved_places_to_trip (importId — keeps pins, photos and tips) or plan around them with plan_trip. Costs Stardust credits, exactly like importing in the app (failed imports refund).
import_textImport places from pasted textWrites, may be destructiveReaches partners- Extract the real places from text the traveler pastes — notes, a friend's list, a blog post, an itinerary email — and save them (with any tips) to their library, exactly like a video import. Runs asynchronously: poll get_import. Costs Stardust credits like importing in the app (failed imports refund). Needs at least 40 characters.
get_importCheck an import's resultsRead-only- Status and results of a video/post import: the extracted places with their areas, notes, per-place tips, and day assignments. While status isn't 'done' (or 'failed'), poll again after ~15s. When done, add_saved_places_to_trip (importId) puts every place into a trip with its pin, photo and tips; plan_trip (savedPlaceIds) plans days around them.
Saved places and travel tips
The traveler's library: save a place for later, tidy folders, drop saved places into a trip with pins intact, and keep the tips notebook.
save_placeSave a place for laterWrites- Save a place to the traveler's library without putting it on a trip yet — 'remember this for my next Lisbon trip'. Optionally file it into a named folder (created if new). Saved places go onto any trip later via add_saved_places_to_trip.
list_saved_placesList saved placesRead-only- The traveler's saved-places library: folders and the places in them (optionally one folder, or 'unsorted'). Put them on a trip with add_saved_places_to_trip (ids or a folder) or plan a trip around them with plan_trip.
manage_saved_placesTidy the saved-places libraryWrites, may be destructive- Housekeeping for the traveler's library in one call: delete places, move places into a folder (or out to unsorted), rename a place, create/rename/delete folders (deleting a folder keeps its places as unsorted). Ids and folder names come from list_saved_places.
add_saved_places_to_tripPut saved places into a tripWrites- Turn the traveler's library into itinerary stops WITH their pins, photos, tips and partner links intact (re-adding by name via add_stops would lose those). Pick places by id (list_saved_places), a whole folder, or everything a video import found (importId from import_video — the video's own day hints place each stop). Whole-city entries are skipped. Places land on dayIndex unless spreadAcrossDays is set.
list_travel_tipsRead the traveler's tips notebookRead-only- The traveler's travel-tips notebook: their own notes plus per-place advice mined by video imports ('go before 8am', 'cash only'). Optionally filter by area name. Surface relevant tips when planning a destination they cover.
manage_travel_tipsEdit the traveler's tips notebookWrites, may be destructive- Add or remove entries in the traveler's travel-tips notebook. Tips can be general or scoped to an area so they resurface when a trip goes there.
Collaboration and trip chat
Invite people to a trip, manage roles, read and post in the crew chat, and vote on stops.
list_crewWho is on a tripRead-only- The trip's crew: owner, collaborators with their roles, and (for the owner) the open invite links. Use it before inviting, removing, or @-mentioning someone in the chat.
invite_to_tripInvite someone to a tripWrites, may be destructiveReaches partners- Create an invite link for a trip, optionally emailed to one person (they must sign in with that email to accept). Roles: editor plans with you, viewer only looks. Anyone who can edit the trip can invite; the link is what to share when no email is given.
manage_crewChange, remove or revoke on a trip's crewWrites, may be destructive- Owner-only crew housekeeping in one call: change a member's role, remove a member, or revoke an open invite. A member may remove themselves (leave) without being the owner. Ids come from list_crew (collaboratorId, invite id).
read_trip_chatRead the trip's group chatRead-only- The latest messages in a trip's crew chat (newest last), including polls. Pass `before` (an ISO timestamp) to page further back.
post_trip_chatPost in the trip's group chatWrites, may be destructive- Say something to the crew in the trip's chat. Mention members by userId (list_crew). Starting the text with @dreamfare summons the in-app planner into the thread.
vote_stopVote on a stopWrites- Thumbs up (1) or down (-1) on a stop the crew is deciding about, or 0 to take a vote back. Tallies appear on get_trip stops as votes {up, down, mine}.
Bookings, receipts and travel essentials
File a booking confirmation on the right stop, read the receipts on a trip, and get eSIM, rental car and transfer links for the destination.
add_receiptAdd a booking confirmation to a tripWrites- Paste a booking confirmation (hotel, flight, tour, train — the email text or its key lines) and Dreamfare files it on the trip: provider, confirmation code, dates and amount are parsed, and when it clearly matches a stop that stop is marked booked. Pass stopId to link it to a specific stop instead of matching by name.
list_receiptsRead a trip's booking confirmationsRead-only- Every receipt filed on a trip with its parsed facts and the stop it's linked to.
travel_extrasTrip essentials: eSIM, rental car, transfersRead-only- Tracked partner links for the trip's destination country: a travel eSIM (data the moment they land), rental cars, airport pickup and private transfers. Booking through these links earns the traveler's commission share, like stops.
Traveler profile
Read the connected account (profile, membership, credits, wallet) and update profile fields.
get_profileRead the traveler's accountRead-only- The traveler's Dreamfare account snapshot: profile, membership tier, AI credits, and wallet balance (commission earned through tracked bookings).
update_profileUpdate the traveler's profileWrites, may be destructive- Update profile fields: display name, bio, home currency, nationality, and the visited-countries list (a FULL replacement — read get_profile first when adding to it). Omitted fields keep their value.
More tools
Tools the server ships that are not filed under a category yet.
search_airportsFind airport codesRead-only- Resolve a city or airport name to IATA codes for search_flights ('Lisbon' → LIS; 'London' → LON, the metro code covering LHR/LGW/STN/LTN, plus each airport). Call it whenever the traveler names a place rather than a code — never guess a code. A city (kind 'city') code searches every airport in that city and is the right pick unless a specific airport was named.
search_flightsSearch and compare flightsRead-onlyReaches partners- Search real flights for a route and date from the configured sources, including direct Kiwi.com search. Compare returned itineraries with `comparison.cheapest`, `fastest` and `best`, and their price/time differences. Prices by booking site exist only when that site actually supplied a quote; never imply that an unlisted vendor was searched. `bookOn` names the site that can open THIS itinerary. Resolve place names with search_airports first (Las Vegas is LAS; Seattle is SEA). All returned amounts and minTotalAmount/maxTotalAmount are whole-party MINOR units. For a budget such as USD 300, use maxTotal:300 with currency:USD; priceBasis:total is the default, or per_person multiplies the budget by adults plus children. Per-person output is an average over adult/child seats including any infant costs, not a separately quoted child or adult fare. Narrow by price range, sorting, stops on each direction, included/excluded airlines, outbound/return departure and arrival clock windows, duration per direction, each connection's layover, cabin/checked bags and self-transfer. Times are local to each departure/arrival airport. To compare routes or dates, search each requested option with the same party, cabin, currency and filters and compare only returned fares. Prices are indicative until booking; disclose separate tickets when recommending self-transfer. Use add_flight_to_trip with the searchId and fare id to save one.
add_flight_to_tripPut a searched fare on a tripWrites- Attach one fare from search_flights to a trip as a flight stop. Pass the searchId and the fare's id exactly as returned. The stop lands on the day matching its departure date. It is a plan, not a booking: the traveler books through the stop's Book button, which opens the site that quoted the price.
Conventions
- Trip and stop ids come from
get_trip; day indexes are 0-based and most writes also accept a date. - Amounts are major units of the stated ISO currency. Stay prices include taxes and fees.
- Writes are enriched shortly after they land (pins, photos, booking links). Re-read the trip before offering booking links.
- Tools marked as reaching partners call live inventory (stays, activities, places, imports) and can take a few seconds.