# AviaSeek - WebMCP for AI agents

> AviaSeek is a global flight metasearch engine. It aggregates prices from airlines and agencies and shows the best flight options (direct or with stops, prices, travel time, baggage rules).

The site implements WebMCP (Model Context Protocol for the Web): browsers with support expose tools via `document.modelContext`. The extended version of this file is `/llms-full.txt`.

## Catalog data (live)

873 cities, 916 airports, 61 airlines, 439 routes in the catalog, 15 help articles.

`searchFlights` contract version: `1.2.0`. Markdown version of any page: path + `.md` (for example `/cities.md`, `/cities/moskva-mow.md`, `/index.md`).

## Server-side MCP (for cloud agents)

Besides the browser WebMCP, AviaSeek provides a **real server-side MCP endpoint** over the Model Context Protocol (Streamable HTTP): `https://aviaseek.com/en/mcp`.

The `searchFlights` tool is available to server-side agents (DeepSeek, Claude, ChatGPT, Cursor, etc.) **directly, without a browser**. Methods: `tools/list`, `tools/call`. The input/output schema is the same as browser WebMCP (see `/llms-full.txt`). Discovery: `https://aviaseek.com/en/.well-known/mcp.json`.

## How to search (3 ways)

1. **MCP** (if the agent has an MCP client): `POST https://aviaseek.com/en/mcp`, tool `searchFlights` (JSON-RPC 2.0, Streamable HTTP).
2. **URL search** (agent can only open links): `https://aviaseek.com/en/search?from=MOW&to=LED&date=tomorrow` -> redirect to the results page with prices and booking links. Params: `from`/`origin`, `to`/`destination`, `date`/`departure_date` (`YYYY-MM-DD`, `DD.MM.YYYY`, `MMDD` or `tomorrow`; not earlier than today and not more than a year ahead), `return`, `adults`, `children`, `infants`, `cabin` (`economy|business|first`). Without a date - redirect to the route page with a price calendar. Help page with an HTML form (works without JavaScript): `https://aviaseek.com/en/search`.
3. **Direct results link**: `https://aviaseek.com/en/results?flightSearch=MOW0920LEDy100` - format `AAAMMDDCCC[MMDD][ycf][adults][children][infants]` (the same value as `view_all_url` in the MCP response). If the page is opened by an agent/bot, the server runs the search itself and returns **HTML with an options list and booking links** - a path for assistants that can only read pages (no MCP/HTTP access).

4. **JSON for agents without MCP** (one GET, ready booking links):
   `https://aviaseek.com/en/api/flights?from=MOW&to=LED&date=tomorrow&limit=5`
   -> `results[]`, where each option has `title`, `price`, `currency`, `transfers`, `duration_minutes`,
   `display_markdown` and **`booking_url`** of the form `/r/<search_id>/<proposal_id>` (valid ~15 minutes).
   Query filters: `direct=1`, `max_price`, `max_transfers`, `transfers=0,1`, `airlines=DP,S7`,
   `with_baggage=1`, `departure_periods=morning,afternoon`, `sort=price_asc|duration_asc|departure_asc|arrival_asc|transfers_asc|recommended`, `limit` (up to 50), `offset`.

> **Date window (common to all ways):** the departure and return dates are not earlier than today and **not more than a year ahead**. The search service does not return prices beyond one year: such a date is rejected as invalid. If the user asks for a distant date - tell them about the limit and offer a date within the window; monthly prices are on the route page (`/search?from=&to=`).
   If params are missing or a date is absent, the `200` response has `status: need_route|need_date` and a sample link.

The city in `from`/`to` can be an IATA city or airport code, a page slug (`moskva-mow`, `sankt-peterburg-led`) or a name ("Moscow", "Saint Petersburg").

## Output contract and filtering (searchFlights, v1.1)

- By default the **20** cheapest options are returned (`limit`, max 100). The rest - via `offset` + `has_more`/`next_offset`; `view_all_url` leads to the results page on the site.
- `sort`: `price_asc` (default), `duration_asc`, `departure_asc`, `arrival_asc`, `transfers_asc`, `recommended`.
- `filters` are applied **before** sorting and slicing: `direct_only` (direct only), `max_transfers`, `transfers[]` (exact stop sets, like the checkboxes on the site), `max_price`, `max_duration_min`, `airlines[]`, `with_baggage`, `with_handbag`, `with_change`, `with_return`, `departure_periods[]`, `arrival_periods[]` (`early_morning` 00:00-06:00, `morning` 06:00-12:00, `afternoon` 12:00-18:00, `evening` 18:00-24:00).
- Examples: "direct only" -> `filters.direct_only=true`; "under 10000" -> `filters.max_price=10000`; "in the morning" -> `departure_periods=["morning"]`; "fastest" -> `sort=duration_asc`.
- Empty results -> `total_after_filters=0` and a `hint` (what exactly to relax).

### How to show the result to the user (required)

- 3-5 options as a list: airline and flight number, departure -> arrival time, number of stops, duration, price and a **clickable link** of the form `[Buy for 3 179](booking_url)`.
- Each option has a ready `display_markdown` field - you can reproduce it as is; it already contains the price and the link.
- Do not answer with a price without a link and do not invent options that are not in `results`.
- `is_complete: false` -> warn that prices are preliminary and call again with the same `search_id`.

## Alice skill (voice)

AviaSeek is available as a skill for Yandex Alice: the user says "Alice, ask AviaSeek to find flights from Moscow to St. Petersburg for tomorrow". The skill searches flights via AviaSeek and reads the best options (top-3) aloud or shows a card with options and booking links on screen devices.

- Webhook: `https://aviaseek.com/en/alice` (POST, Yandex Dialogs protocol, response limit 4.5 s).
- The search is asynchronous (split-turn): "find flights" starts a search; it continues on the phrase/button "check the result".
- Booking links - the purchase page `https://aviaseek.com/en/r/<searchId>/<proposalId>`.

## WebMCP tools

- [searchFlights](/): search flights by route and dates. Returns a list of flights with prices, airlines, times and a booking link.
  - Params: `origin`, `destination` (IATA code, 3 letters, e.g. MOW, LED, PAR), `departure_date` (YYYY-MM-DD, required), `return_date` (optional, for round-trip), `adults`/`children`/`infants` (passenger counts), `cabin` (`economy`|`business`|`first`).
  - Call: `document.modelContext.executeTool('searchFlights', {...})`.
  - List: `await document.modelContext.getTools()`.

## Key site sections

- Flight search: https://aviaseek.com/en/
- Results: https://aviaseek.com/en/results
- City catalog: https://aviaseek.com/en/cities
- Route catalog: https://aviaseek.com/en/directions
- Airport catalog: https://aviaseek.com/en/airports
- Airline catalog: https://aviaseek.com/en/airlines
- FAQ: https://aviaseek.com/en/faq

## Contacts

- Home page: https://aviaseek.com/en/