Motus

Motus finds group meetup flights. You give it a destination, a set of travelers with their home airports, and a date range. It searches each person's flights and returns options where everyone lands within one arrival window of each other. Every price is all-in: the base fare plus each traveler's checked and carry-on bag fees. With the live RouteStack provider the bag fees are estimated, so the total is a close approximation rather than the exact airline charge.

Quick start

The app runs with no configuration. It ships with a built-in mock provider that returns demo flights, so you can try it without any API keys.

pnpm install
pnpm dev

Then open http://localhost:3000. The form starts with three sample travelers and a destination already filled in, so you can press "Find meetups" right away.

Related MCP server: Aerospace MCP

Using real fares

To search live fares and schedules, switch to the RouteStack provider. Copy .env.example to .env.local and set the provider and your credentials:

FLIGHT_PROVIDER=routestack
ROUTESTACK_API_KEY=your-key
ROUTESTACK_API_SECRET=your-secret

The server validates this at startup. If you set FLIGHT_PROVIDER=routestack without both credentials, it fails loudly and tells you what is missing. ROUTESTACK_BASE_URL defaults to the public endpoint and only needs setting if you point at a different host.

The RouteStack adapter authenticates with an HMAC-signed request, caches the partner token, and parses each fare into Motus's flight shape. When RouteStack returns a flight for a different airport than the one requested, the adapter logs that substitution so you can see when upstream results do not match the exact origin and destination you asked for.

MCP server

Motus exposes a Code-Mode MCP endpoint at POST /api/mcp. It offers two tools. An agent calls describe to learn the motus SDK: the available functions, their arguments, and return shapes. The agent then writes a short JavaScript program and sends it to execute, which runs the program against that SDK and returns its result.

const airports = await motus.searchAirports("denver");
return airports;

The guest code runs in a locked-down sandbox with no network, environment, or filesystem access, so it can only call the SDK functions Motus provides. The endpoint is rate-limited.

Deploying

Set SITE_URL to the public base URL of your deployment, for example https://your-domain.com. Motus uses it for canonical tags, the sitemap, Open Graph image URLs, and robots. It is required in production. On Vercel it falls back to the deployment URL when unset, but a stable custom domain is better for search engines. In local development it defaults to http://localhost:3000.

Scripts

Architecture

How the matching works

The matcher anchors an arrival window at each flight's arrival time across all travelers. For each anchor it takes every traveler's cheapest all-in flight that lands inside that window. If even one traveler has no flight in the window, that anchor is dropped. The surviving options are ranked by your objective: min_total puts the cheapest combined cost first, and min_max puts the lowest single fare first so no one person carries an outsized share.