Whentofly MCP Server

Find the cheapest round-trip across a FLEXIBLE multi-month date window with a min/max trip length — e.g. "10–15 days, anytime Sep–Nov". Search a broad date window rather than requiring the traveler to choose exact dates first. First call the search_locations MCP tool for city or airport names, then pass each returned airport:AAA or city:AAA value unchanged as origin/destination (explicit legacy IATA codes remain supported). Dates are OPTIONAL: add an earliest/latest window when the traveler has one, or omit them (or give just one side) and a sensible default window is searched — metadata.window_defaulted says so and query echoes the window used, so a dateless call always returns flights instead of an error. Add min/max trip duration; get back a ranked list of the cheapest fares (with booking links) plus a price verdict — an honest read of whether the cheapest fare is low, typical, or high versus the route's usual price, or unknown when we lack a usable typical-price band (a price-level read, not a buy-now-or-wait timing prediction). Non-economy requests may return action-bound Google Flights seller quotes or separate route-price evidence in metadata.route_price_check. For a specific route, set checked_bags=1 when the traveler needs one checked bag, then inspect each result's price_basis; anywhere discovery does not support baggage pricing. Checked-bag searches still run seller enrichment but set the fare-only verdict and metadata.route_price_check to null; verify=full does not override that boundary. Use it for any flight question where the dates are flexible, unknown, or the user wants the cheapest time to fly. If a window comes back thin or cannot fit the return, the search widens it one step itself and reports that in metadata.hints — no second call needed. A city:/airport: prefix that contradicts its code (city:CDG names an airport, airport:PAR names a city) is likewise searched as the identity the catalog does know, with a selector_corrected entry in metadata.hints naming the requested and used tokens. Dates already in the past get the same treatment: a window that only STARTS in the past is searched from today with a window_clamped entry in metadata.hints, and a window that has already ENDED is not searched at all — the results are empty and a window_in_past entry names a suggested window to ask for instead, so do not retry the same dates. If metadata.refresh_hint is present, this response shipped without something a repeat call can add: issue the same call again immediately (do not sleep or poll) and read refresh_hint.action for what will be included. If you can wait longer for that best-effort cross-check, set verify=full. It uses a longer ~35s budget, but never treats a different airline, itinerary, gate, or booking URL as verification of the displayed offer. Pass sellers=false when the traveler wants the price picture but is not booking through this answer: it skips the live seller-quote wave, so the ranked calendar fares, booking links and metadata.route_price_check still come back but metadata.seller_enrichment_status is `skipped` and no seller quote, seller-level baggage fee or direct seller action is resolved. Provider failure, unavailability, or a spend cap can still return only cached indicators; always inspect metadata.seller_enrichment_status (`applied` means complete date-pair coverage put Serp-derived seller data in results; `complete` means the selected plan and action resolution completed without such data entering results; `partial` means date-pair or direct-action coverage has gaps though valid seller data may still rank; `skipped` is reserved for response surfaces where enrichment does not apply) and metadata.seller_enrichment_coverage. That object reports the theoretical query-valid date pairs and how many were targeted/searched; it is not exhaustive provider inventory. Default requests target at most three pairs, while explicit verify=full targets at most seven with bounded longer budgets. Inspect metadata.freshness, and metadata.route_price_check.

Resolve a city or airport name or code before searching flights. Returns typed values such as city:SHA to search every catalog airport in Shanghai or airport:SHA for Hongqiao only. Pass the selected value unchanged to search_flights. Ask the traveler when multiple results are plausible.