Tutorial: Flight Search - Gnist Context

Transport

Data source: Amadeus GDS

Overview

Flight Search wraps Amadeus GDS, handling authentication, pagination, and rate limits for you. This tutorial covers all 7 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-flights": {
      "url": "https://context.gnist.ai/mcp/flights/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

`search_flights`

Search for flights across multiple data sources. Queries the Amadeus GDS API. Additional sources (Kiwi, SAS EuroBonus, Seats.aero) are planned. Results are sorted by price or points depending on mode. Examples: search_flights(origin="OSL", destination="JFK", departure_date="2026-06-15") search_flights(origin="OSL", destination="JFK", departure_date="2026-06-15", return_date="2026-06-22", cabin_class="business") search_flights(origin="OSL", destination="JFK", departure_date="2026-06-15", mode="award")

Parameter	Type	Required	Description
`origin`	string	required	Origin IATA airport code (e.g. 'OSL').
`destination`	string	required	Destination IATA airport code (e.g. 'JFK').
`departure_date`	string	required	Departure date (YYYY-MM-DD).
`return_date`	any	optional	Return date for round-trip (YYYY-MM-DD). Omit for one-way.
`adults`	integer	optional	Number of adult passengers. (default: `1`)
`cabin_class`	any	optional	Cabin class: economy, premium_economy, business, or first.
`mode`	string	optional	Search mode: 'revenue' (paid flights), 'award' (points/miles), or 'all'. (default: `all`)
`max_results`	integer	optional	Maximum number of results to return. (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_flights", "arguments": {"origin": "'OSL'", "destination": "'JFK'", "departure_date": "2025-01-15"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'departure_date': '2025-01-15',
                          'destination': "'JFK'",
                          'origin': "'OSL'"},
            'name': 'search_flights'}},
)
print(resp.json())

`search_award_flights`

Search specifically for award flights (points/miles redemptions). Queries for award flights (points/miles). Currently uses Amadeus; SAS EuroBonus and Seats.aero are planned. Results are sorted by points cost. Examples: search_award_flights(origin="OSL", destination="JFK", departure_date="2026-06-15") search_award_flights(origin="OSL", destination="LAX", departure_date="2026-07-01", cabin_class="business")

Parameter	Type	Required	Description
`origin`	string	required	Origin IATA airport code (e.g. 'OSL').
`destination`	string	required	Destination IATA airport code (e.g. 'JFK').
`departure_date`	string	required	Departure date (YYYY-MM-DD).
`return_date`	any	optional	Return date for round-trip (YYYY-MM-DD). Omit for one-way.
`adults`	integer	optional	Number of adult passengers. (default: `1`)
`cabin_class`	any	optional	Cabin class: economy, premium_economy, business, or first.
`max_results`	integer	optional	Maximum number of results to return. (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_award_flights", "arguments": {"origin": "'OSL'", "destination": "'JFK'", "departure_date": "2025-01-15"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'departure_date': '2025-01-15',
                          'destination': "'JFK'",
                          'origin': "'OSL'"},
            'name': 'search_award_flights'}},
)
print(resp.json())

`list_flight_sources`

List all registered flight data sources and their status. Shows which sources are available, what modes they support (revenue/award), and whether they are currently enabled. Examples: list_flight_sources()

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_flight_sources", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_flight_sources'}},
)
print(resp.json())

`sas_awards_search`

Search for SAS EuroBonus award seat availability on routes from Oslo to North America. Checks Business and Premium Economy award seats on SAS flights. This is a slow tool (15-90 seconds depending on destination count) as it queries each destination sequentially. Examples: sas_awards_search() sas_awards_search(destinations=["MIA", "LAX"], priority_only=True) sas_awards_search(passengers=2, max_stay_days=14)

Parameter	Type	Required	Description
`destinations`	any	optional	IATA codes to check (e.g. ['MIA', 'LAX']). Omit to check all 11 configured destinations.
`passengers`	integer	optional	Number of seats required on both legs. (default: `3`)
`min_stay_days`	integer	optional	Minimum stay duration in days. (default: `2`)
`max_stay_days`	integer	optional	Maximum stay duration in days. (default: `10`)
`priority_only`	boolean	optional	Return only results for priority destinations (MIA, LAX). (default: `False`)

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "sas_awards_search", "arguments": {"destinations": "['MIA'"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'destinations': "['MIA'"},
            'name': 'sas_awards_search'}},
)
print(resp.json())

`sas_awards_list_destinations`

List all configured SAS EuroBonus award search destinations. Shows destination codes, names, cabin class rules, and priority flags. Examples: sas_awards_list_destinations()

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "sas_awards_list_destinations", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'sas_awards_list_destinations'}},
)
print(resp.json())

`sas_awards_get_config`

Return the current SAS EuroBonus search configuration. Shows origin, default passenger count, stay ranges, and lookahead window. Examples: sas_awards_get_config()

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "sas_awards_get_config", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'sas_awards_get_config'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/flights/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/flights/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_flights to find items, then sas_awards_get_config to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Flight Search provide?

Multi-source flight search — currently Amadeus GDS, with Kiwi, SAS EuroBonus, and Seats.aero planned. It exposes 7 tools: search_flights, search_award_flights, list_flight_sources, sas_awards_search, sas_awards_list_destinations, sas_awards_get_config, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Flight Search API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 7 tools.

Getting Started with Flight Search