search_flights
Read-onlyIdempotent
Search real-time flight prices and schedules from 800+ airlines between two cities. Filter by date, cabin class, stops, and passengers to find and compare airfares.
Instructions
Search airline flights / airfares between two cities by date, cabin class (economy / premium economy / business / first), and number of passengers. Returns available flights from 800+ airlines (Duffel) with real-time pricing, schedules, and stops. Uses IATA airport codes (e.g., MIA, JFK, LAX, LHR). Use this when the user wants to book a flight, fly somewhere, find airfare, or compare airlines.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | IATA origin airport code (e.g., 'MIA', 'JFK', 'LAX') | |
| destination | Yes | IATA destination airport code | |
| departure_date | Yes | Departure date (YYYY-MM-DD) | |
| return_date | No | Return date for round-trip (YYYY-MM-DD). Omit for one-way. | |
| passengers | No | Number of passengers (1-9, default: 1) | |
| cabin_class | No | Cabin class (default: economy) | |
| max_price_usd | No | Maximum total price in USD | |
| nonstop_only | No | Only show nonstop flights (default: false) |
Implementation Reference
- src/server.ts:204-226 (registration)Tool definition (name, description, inputSchema) for 'search_flights' registered in ALL_TOOLS array. This is where the tool is declared with its schema for MCP discovery.
{ name: "search_flights", description: "Search airline flights / airfares between two cities by date, cabin class (economy / premium economy / business / first), and number of passengers. Returns available flights from 800+ airlines (Duffel) with real-time pricing, schedules, and stops. Uses IATA airport codes (e.g., MIA, JFK, LAX, LHR). Use this when the user wants to book a flight, fly somewhere, find airfare, or compare airlines.", inputSchema: { type: "object" as const, properties: { origin: { type: "string", description: "IATA origin airport code (e.g., 'MIA', 'JFK', 'LAX')" }, destination: { type: "string", description: "IATA destination airport code" }, departure_date: { type: "string", description: "Departure date (YYYY-MM-DD)" }, return_date: { type: "string", description: "Return date for round-trip (YYYY-MM-DD). Omit for one-way." }, passengers: { type: "number", description: "Number of passengers (1-9, default: 1)" }, cabin_class: { type: "string", enum: ["economy", "premium_economy", "business", "first"], description: "Cabin class (default: economy)", }, max_price_usd: { type: "number", description: "Maximum total price in USD" }, nonstop_only: { type: "boolean", description: "Only show nonstop flights (default: false)" }, }, required: ["origin", "destination", "departure_date"], }, }, - src/server.ts:744-748 (handler)Handler for 'search_flights' tool execution. Calls apiCall for POST /v1/flights/search with user args, then trims the response via trimFlightResponse.
case "search_flights": { const result = await apiCall("POST", "/v1/flights/search", args); const trimmed = trimFlightResponse(result); return { content: [{ type: "text", text: JSON.stringify(trimmed, null, 2) }] }; } - src/server.ts:633-674 (helper)trimFlightResponse helper function that slices raw flight data to 25 results and maps fields (offer_id, airline, cabin_class, price, stops, outbound/inbound segments, etc.) for LLM consumption.
function trimFlightResponse(raw: any, limit = 25): any { const data = Array.isArray(raw?.data) ? raw.data : []; const trimmed = data.slice(0, limit).map((f: any) => ({ offer_id: f.offer_id || f.id, duffel_offer_id: f.duffel_offer_id, airline_name: f.airline_name || f.airline, airline_code: f.airline_code, flight_number: f.outbound?.[0]?.flight_number || f.flight_number, cabin_class: f.cabin_class, fare_brand: f.fare_brand, price_usd: f.price_usd, stops: f.stops, total_duration_minutes: f.total_duration_minutes, refundable: f.refundable, baggage: f.baggage, outbound: (f.outbound || []).map((s: any) => ({ origin: s.origin, destination: s.destination, airline_code: s.airline_code, flight_number: s.flight_number, departure_time: s.departure_time, arrival_time: s.arrival_time, duration_minutes: s.duration_minutes, cabin_class: s.cabin_class, })), inbound: f.inbound ? (f.inbound || []).map((s: any) => ({ origin: s.origin, destination: s.destination, airline_code: s.airline_code, flight_number: s.flight_number, departure_time: s.departure_time, arrival_time: s.arrival_time, duration_minutes: s.duration_minutes, cabin_class: s.cabin_class, })) : null, cancel_policy: (f.cancel_policy || "").slice(0, 200), })); return { data: trimmed, meta: { count: trimmed.length, total_returned: data.length, trimmed_for_llm: data.length > limit }, }; } - src/server.ts:208-225 (schema)Input schema for search_flights defining properties: origin (required), destination (required), departure_date (required), return_date, passengers (1-9), cabin_class (economy/premium_economy/business/first), max_price_usd, nonstop_only.
inputSchema: { type: "object" as const, properties: { origin: { type: "string", description: "IATA origin airport code (e.g., 'MIA', 'JFK', 'LAX')" }, destination: { type: "string", description: "IATA destination airport code" }, departure_date: { type: "string", description: "Departure date (YYYY-MM-DD)" }, return_date: { type: "string", description: "Return date for round-trip (YYYY-MM-DD). Omit for one-way." }, passengers: { type: "number", description: "Number of passengers (1-9, default: 1)" }, cabin_class: { type: "string", enum: ["economy", "premium_economy", "business", "first"], description: "Cabin class (default: economy)", }, max_price_usd: { type: "number", description: "Maximum total price in USD" }, nonstop_only: { type: "boolean", description: "Only show nonstop flights (default: false)" }, }, required: ["origin", "destination", "departure_date"], },