Skip to main content
Glama

flightops-mcp

ci

A governed Model Context Protocol server that lets an AI agent ask questions about the operational state of an airport — and refuses to answer badly.

Most MCP examples on GitHub are a stdio server with two read-only tools. This one is built around the parts that actually break in production: OAuth2 client-credential token lifecycles, a credit-metered upstream with a real 429 contract, honest reporting of missing data, and logs that never contain a credential or a passenger identifier.

  • Protocol: MCP revision 2026-07-28 (stateless: no initialize handshake, no session id, per-request capability negotiation), via the Python SDK's MCPServer.

  • Verified: 73 passed, 0 skipped · ruff clean · mypy --strict clean · a live end-to-end stdio run against AviationWeather.gov returning real METARs.

  • Cost: zero. Every upstream is free; the authenticated one is optional.


Requirements → what is actually in the repo

Capability

Where it lives

How it is proven

MCP tools with typed schemas

src/flightops_mcp/server.py

test_all_tools_are_published_with_schemas asserts every tool has a usable description and an object schema

OAuth2 client credentials (M2M)

opensky_token.py

test_fifty_concurrent_callers_make_exactly_one_token_request

Token lifecycle (expiry, revocation)

opensky_token.py, opensky.py

refresh-ahead inside the skew; a 401 invalidates and retries once

Rate limits

http.py, opensky.py

429 + Retry-After / X-Rate-Limit-Retry-After-Seconds honoured when short, surfaced as data when long

API budget / least privilege

opensky.py credit ledger

test_local_credit_budget_stops_a_runaway_loop

REST integration, no-auth path

weather.py

live NOAA call in CI (advisory job)

Safe logging, no PII

telemetry.py

canary tests: a planted token and passenger record must not appear in emitted logs

Ground-truth reference data

airports.py + scripts/build_airports_db.py

distance validated two independent ways

Failures the model can act on

errors.py

every failure carries code, message, hint, retry_after_s

Containerisation

Dockerfile, docker-compose.yml

CI builds the image, asserts non-root, asserts the reference DB is baked in

Version control hygiene

.gitignore, .gitattributes, uv.lock

no secrets, no multi-megabyte data blobs, LF-normalised


Related MCP server: AirLabs MCP Server

Architecture

        MCP host (Claude Desktop, Inspector, an agent loop)
                              │  JSON-RPC over stdio or Streamable HTTP
                              ▼
                    ┌───────────────────┐
                    │  flightops-mcp    │  6 typed tools, guarded
                    │  (MCPServer)      │  failures become data, never 500s
                    └─────┬───────┬─────┘
             OAuth2 M2M   │       │   no auth
        client_credentials│       │
                   ┌─────▼─────┐ ┌─▼──────────────────┐ ┌──────────────────────┐
                   │ OpenSky   │ │ AviationWeather.gov│ │ OurAirports SQLite   │
                   │ REST API  │ │ (NOAA)             │ │ (bundled, offline)   │
                   │ credits   │ │ METAR / TAF        │ │ 49,353 airports      │
                   │ 429 wall  │ │ 204 = no data      │ │ public domain        │
                   └───────────┘ └────────────────────┘ └──────────────────────┘

Three upstreams with three different auth models is the point: the tool layer must not care, and the governance layer must hold for all of them.

Quickstart

uv sync

# The image and CI bake this from the bundled seed; locally it is one command.
uv run python scripts/build_airports_db.py --csv data/airports_seed.csv

# No credentials needed for this much:
uv run flightops-mcp           # stdio, for Claude Desktop / mcp dev

To unlock the traffic and movement tools, create a free account at https://opensky-network.org (Account → API Client) and put the pair in .env:

FLIGHTOPS_OPENSKY_CLIENT_ID=your-id-api-client
FLIGHTOPS_OPENSKY_CLIENT_SECRET=your-secret

Then in claude_desktop_config.json:

{
  "mcpServers": {
    "flightops": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/flightops-mcp", "flightops-mcp"]
    }
  }
}

The tools

Tool

Upstream

Credentials

Cost

resolve_airport

OurAirports (local)

none

free, offline

airport_weather

AviationWeather.gov

none

free

airport_live_traffic

OpenSky /states/all

OAuth2

1–4 credits

airport_movements

OpenSky /flights/*

OAuth2

4 credits per direction

disruption_triage

all three, composed

OAuth2 for the traffic half

~9 credits

upstream_status

process state

none

free

Design decisions worth defending

  1. A 429 is a contract, not noise. If the upstream says "retry in 3 s" and our ceiling is 5 s, the client waits and retries exactly once. If it says "retry in 900 s", the call returns a structured error carrying that number. Sleeping fifteen minutes inside a tool call is not resilience; it is a hung agent.

  2. Tokens are single-flight. Fifty concurrent tool calls that find an empty cache produce one token request, not fifty. The lock is double-checked so the winner refreshes and the rest reuse.

  3. Credits are charged before the request. A call that times out still spends upstream budget, so the local ledger must record it too or the guard under-reports real spend. /states/all costs a documented function of bounding-box area — BBox.credit_cost mirrors that table and the test pins every band boundary.

  4. Absence of data is never "all clear". A 204 from NOAA, an empty movements list, and a missing credential produce three different explicit unknowns entries. An empty result from an ADS-B feed means "nothing heard", which is not "nothing happening".

  5. Redaction is tested, not asserted. A canary string is planted as a token, a PNR and a passenger name; the emitted log lines are parsed and searched for it. GDPR claims that are not executed are marketing.

  6. Triage degrades to unknown, not to low. Without credentials the composite tool still returns weather, and reports severity unknown with the reason — it does not imply the airport is fine because it could not see the traffic.

  7. Provenance travels with the data. Every payload names the upstream and its licence, so an operator can see that "traffic" means ADS-B estimates and "weather" means a government observation.

What running it actually found

Two defects that reviewing the code would not have caught, both now pinned by tests:

  • NOAA rejects hours on /taf. GET /api/data/taf?ids=ESGG&format=json&hours=12 returns HTTP 400 {"status":"error","error":"Unexpected query parameter provided"}, while /metar accepts it happily. The first live run failed here; test_taf_request_omits_the_hours_parameter is the regression.

  • A monotonic clock is the wrong clock for epoch maths. The runtime originally defaulted to time.monotonic(), which is right for token TTLs and wrong for movement windows — it would have asked OpenSky for traffic in January 1970. Wall clock is now the default, with the reasoning in a comment.

Live data also carries "visib": "6+" — a string, not a number — so a strict isinstance check would have silently dropped real observations and lost a flag. _number() coerces it, and a test covers it.

The test suite

tests/test_token.py          7   caching, single flight, skew, rejection, malformed response
tests/test_http.py          12   Retry-After (seconds + HTTP-date), retry counts, 429 passthrough
tests/test_opensky.py       21   credit table, decoding, 429 policy, 401 recovery, budget guard
tests/test_airports.py       9   build, resolve, nearest, cross-checked distances
tests/test_weather.py        8   no-data semantics, field mapping, flag thresholds
tests/test_server_tools.py  11   end-to-end through a real MCP client, in memory
tests/test_redaction.py      5   keyed secrets, nested structures, bearer scrubbing, canary
                            --
                            73

No network, no sleeps, no real clock: transports, sleep and clock are injected. The suite runs on a bare interpreter in under 10 seconds, and CI fails if any test reports as skipped.

What this deliberately does not do

  • No write operations. Nothing here rebooks a passenger. The scope is observation and triage; a write path needs an idempotency story and a human-approval gate that this repo does not claim.

  • No LLM in the loop. The server is the hard part and it stays testable without a model. Adding an agent loop on top is the next increment, not a hidden requirement.

  • No Kubernetes, no frontend, no vector database. Each would be a week of work that demonstrates nothing about integration engineering.

  • ADS-B is not a schedule. OpenSky deduces arrivals and departures from transponder positions, so origin and destination fields are estimates. That caveat is in the tool description, not only here.

Data sources and licences

Source

Data

Licence / terms

OpenSky Network

state vectors, movements

Free for personal and non-profit use; commercial use requires OpenSky's consent

AviationWeather.gov (NOAA)

METAR, TAF

US Government open data, public domain

OurAirports

airports, runways, navaids

Public domain

This project is the personal-use case: no commercial deployment, no redistribution of upstream data.

Roadmap

v0.1.0 ships the governed tool layer and its test suite. ROADMAP.md is the phased plan to v1.0: auth-hardened remote server with OBO, observability and a runbook, an agent loop with a human approval gate, an evaluation harness, then hardening and documentation.

Roadmap → next milestones

Near-term milestones

  • Streamable HTTP server with MCP-spec OAuth 2.1 resource-server behaviour (JWKS validation, scope challenges in WWW-Authenticate, no token passthrough)

  • On-behalf-of token exchange (RFC 8693) so a user's identity, not a service's, reaches the upstream

  • OpenTelemetry traces with traceparent propagated into _meta as the 2026-07-28 revision specifies

  • An agent loop with a human-approval gate for the first write tool

  • Tool-calling eval harness: golden scenarios scored for tool choice, argument validity and refusal

Available Tools

6 tools
airport_live_trafficA

Return aircraft currently within a radius of an airport.

Costs 1 OpenSky credit for a box up to 25 square degrees, up to 4 for a very
large radius. Aircraft are sorted by most recently heard.

Args:
    airport: ICAO code, e.g. ESGG.
    radius_nm: Search radius in nautical miles (5-200).
    max_aircraft: Cap on returned aircraft (1-200).

Inputs: airport (required), radius_nm, max_aircraft. Returns: object

airport_movementsA

List estimated arrivals and/or departures for an airport.

Each direction costs 4 OpenSky credits for a live window of under 24 hours.
OpenSky derives these movements from ADS-B, so they are estimates: the
origin/destination fields are inferred from the first and last seen position.

Args:
    airport: ICAO code, e.g. ESGG.
    direction: "arrival", "departure", or "both".
    window_minutes: Look-back window in minutes (5-60; OpenSky serves at most
        one hour of history).

Inputs: airport (required), direction, window_minutes. Returns: object

airport_weatherA

Return the latest METAR and TAF for an airport, plus impact flags.

Needs no credentials and spends no OpenSky credits.

Args:
    airport: ICAO code, e.g. ESGG.

Inputs: airport (required). Returns: object

disruption_triageA

Assess whether an airport is currently disrupted: weather, traffic, movements.

This is the composite tool an agent should reach for first. It makes one
weather call (free), one movements call per direction and one traffic call
(OpenSky credits), then reports severity together with its reasons and its
unknowns. Severity is advisory only.

Args:
    airport: ICAO code, e.g. ESGG.
    radius_nm: Traffic search radius in nautical miles (5-200).

Inputs: airport (required), radius_nm. Returns: object

resolve_airportA

Resolve an airport from an ICAO/IATA code or a name fragment.

Offline and free: reads the bundled OurAirports reference database, so it
costs no API credits and works with no credentials configured.

Args:
    query: ICAO (ESGG), IATA (GOT), or part of an airport name.
    limit: Maximum matches to return (1-20).

Inputs: query (required), limit. Returns: object

upstream_statusA

Report upstream health, credit spend and credential state.

Use before blaming the data: it separates "no credentials", "rate limited"
and "quiet airspace".

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a fairly distinct concern (weather, live traffic, movements, health, airport lookup), and descriptions explicitly separate free vs credit-spending calls. The main overlap is disruption_triage, which internally duplicates weather/traffic/movements, so an agent must judge whether to call the composite or the primitives — the description guides this but does not eliminate the choice. airport_live_traffic vs airport_movements is also a subtle distinction (aircraft currently present vs inferred arrivals/departures) that takes careful reading.

    Naming Consistency3/5

    All names are snake_case and readable, but the pattern is mixed: three tools use an 'airport_' prefix while disruption_triage, upstream_status, and resolve_airport do not. Verb style is also inconsistent — resolve_airport is verb_noun while the rest are noun-first (noun_noun or adjective_noun), so there is no predictable verb_noun convention to rely on.

    Tool Count5/5

    Six tools is well within a tight, purposeful scope for an airport-centric flight ops server. Every tool has a clear job: reference lookup, weather, traffic, movements, composite triage, and diagnostics — no filler or near-duplicates that could be consolidated without losing function.

    Completeness4/5

    The read-only airport situational-awareness domain is well covered: weather, live traffic, movements, composite severity, identifier resolution, and upstream/credential diagnostics with an explicit escape hatch for failures. Minor gaps remain — no aircraft/callsign-level lookup, no historical or delay-statistics access beyond the one-hour movements window, and no way to pull deeper airport metadata from resolve_airport.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI assistants with access to real-time flight data, airport schedules, delays, and aviation reference databases through natural language queries.
      12
      191 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides aviation weather data (METAR, TAF, station search) with a unique assess_conditions tool that returns flight category, confidence, and an escalation gate to indicate when human review is needed.
      4
      46 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI assistants with real-time and forecast airport intelligence, including security wait times, FAA delays, EU border queues, lounge and terminal info, aviation weather, and baggage performance for over 8,000 airports.
      MIT