Skip to main content
Glama
Sign In
FlightByte MCP Server

FlightByte MCP Server

Official
by FlightByte-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Create a subscription

create_subscription

Watch a specific flight and receive signed webhook POSTs for every status, gate, terminal, delay, or baggage change until the flight ends. Relay the returned signing secret to the user.

Instructions

Watch a flight: FlightByte polls it on an adaptive schedule and POSTs a signed webhook to webhookUrl for every change (status, gates, terminals, times, delays, departure, arrival, baggage carousel, cancellation, diversion, aircraft, route, codeshares) until the flight is over. Each new subscription counts as a watched flight on the user's plan (Free: 3 per month) and starts outbound requests to the URL, so only call this when the user asked to watch or be notified about a specific flight and gave the webhook URL. If the flight number operates more than one leg that day the call is refused with the list of legs: pass origin. Flights up to seven days ahead are accepted and wait as pending until published. The response includes the signing secret in full; this is the only time it is shown, so relay it to the user to store for webhook signature verification. Pass Idempotency-Key to make a retry return the same subscription.

Input Schema

NameRequiredDescriptionDefault
dateYesLocal departure date at the origin airport, YYYY-MM-DD. A flight that leaves at 23:50 and lands the next morning belongs to the day it left. Live records cover a few days back to about two days ahead.
eventsNoChange types to deliver; omit to deliver all 23. Common picks: "flight.departed", "flight.arrived", "flight.cancelled", "flight.diverted", "departure.gate.changed", "arrival.baggage.changed", "delay.increased".
originNoDeparture airport, IATA code (e.g. "IST"; the upstream code such as "ISL" also works). Picks the leg when the flight number operates more than one leg that day.
secretNoBring your own signing secret, only when the user explicitly provides one their receiver already uses. Normally omit it: FlightByte generates one and returns it once.
carrierYesAirline code: the 2-character IATA code (e.g. "TK") or 3-character ICAO code (e.g. "THY"). For flight "TK1848" this is "TK".
headersNoExtra HTTP headers sent with every delivery, e.g. {"Authorization": "Bearer <receiver token>"}.
flightIdNoExact leg pick: a providerFlightId from a previous response's `alternates`, or a flightId from an error's list of legs.
metadataNoString map echoed back in every webhook, e.g. {"bookingId": "BK-1042"}. Use it to tie deliveries to your own records.
webhookUrlYesThe user's public http(s) endpoint that receives a signed POST for every change. Addresses that resolve to private, loopback or link-local ranges are refused. Never invent one.
destinationNoArrival airport, IATA code (e.g. "JFK"). Narrows further when several legs leave the same airport.
flightNumberYesFlight number without the airline code: 1 to 4 digits and an optional letter suffix. For "TK1848" this is "1848". Leading zeros are ignored.
Idempotency-KeyNoAny unique string (e.g. a UUID). Replaying the same key within 24 hours returns the original subscription instead of creating a second one.
delayThresholdMinutesNoDelay changes smaller than this many minutes are not delivered. 1 to 240; the default is 1.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is already structured. The description still adds substantial behavior beyond that: per-plan quota counting, outbound POSTs to the user URL, refusal on ambiguous legs, pending state for flights up to seven days ahead, and the one-time signing secret. The one caveat is the idempotentHint=false annotation alongside the Idempotency-Key paragraph, which could read as tension even though it is really 'not idempotent by default'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and every sentence carries real information, but the block is dense and sentence-heavy for a 13-parameter tool. A short bulleted split between 'when to use', 'side effects', and 'response' would make it easier to scan without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 13 parameters, nested objects, no output schema, and only sparse annotations, the description covers the high-risk behaviors an agent must know: quota, outbound requests, leg ambiguity, pending publication, and one-time secret handling. What remains thin is response shape and webhook payload contents, which are partly implied but not documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description still adds cross-parameter semantics the schema cannot: `origin` is the disambiguator when a flight number operates multiple legs, `Idempotency-Key` changes retry behavior, and the generated `secret` is returned once and should normally be omitted unless the user supplies one. It does not explain the event-filter or delay-threshold parameters, but those are already well described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource ('Watch a flight') and immediately explains the mechanism: FlightByte polls on an adaptive schedule and POSTs a signed webhook for every change. It is clearly distinguishable from the sibling read/management tools (list_subscriptions, update_subscription, delete_subscription) because it describes creating a new watched flight with an endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States an explicit trigger ('only call this when the user asked to watch or be notified about a specific flight and gave the webhook URL') and warns about quota consumption (Free: 3 per month) and outbound requests. It also gives the concrete fallback for multi-leg flights: the call is refused with a leg list so pass `origin`.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools