FlightByte MCP Server

Quick start

1. Get a free API key at app.flightbyte.dev/signup.

2. Connect the server. Use the hosted one, or run it locally:

   	Address	Key
   Hosted	https://mcp.flightbyte.dev/mcp	Authorization: Bearer <key> header
   Local	npx -y @flightbyte/mcp	FLIGHTBYTE_KEY environment variable

   In Claude Code, for example:

   claude mcp add --transport http flightbyte https://mcp.flightbyte.dev/mcp \
     --header "Authorization: Bearer $FLIGHTBYTE_KEY"

   Every other client is under Install.

3. Ask: "Is TK1848 on time today?"

The docs tools work without a key, so an assistant can read the documentation before you have signed up.

Related MCP server: Aviation MCP Server

What you can ask

Tools

Docs: no key needed.

Flights: read-only.

Subscriptions

Parameters carry the API's own names (carrier, flightNumber, date, origin, webhookUrl, Idempotency-Key, …), and the test suite checks every one against the OpenAPI document. Results are the API's JSON, as text and as structured content.

Built for assistants

• Your key stays yours. The local server reads FLIGHTBYTE_KEY. The hosted server reads the key from each request's header, uses it for that request only, and never stores or logs it.

• Secrets stay out of the chat. There are no tools to reveal or rotate a webhook signing secret, because either would put it into the model's context and from there into transcripts. create_subscription returns the secret once, as the API does, and tells the assistant to hand it to you. Reveal or rotate secrets in the dashboard.

• Clients know what is safe. Read-only tools are marked read-only and delete_subscription is marked destructive, so clients can ask before running it. create_subscription tells the model it creates a billable watched flight and should only run when you ask for one.

• Errors say what to do next. A flight number that flies twice comes back with its legs and "pass origin". A 429 comes back with how long to wait. A 402 watched_flight_limit says to stop, when the allowance resets, and where to upgrade.

• Docs fetches stay on flightbyte.dev. get_doc_page refuses every other host.

Install

Replace YOUR_FLIGHTBYTE_KEY with your key. Every client below can use the hosted server; the local one needs Node.js 20 or later.

Hosted:

claude mcp add --transport http flightbyte https://mcp.flightbyte.dev/mcp \
  --header "Authorization: Bearer YOUR_FLIGHTBYTE_KEY"

Local:

claude mcp add flightbyte --env FLIGHTBYTE_KEY=YOUR_FLIGHTBYTE_KEY \
  -- npx -y @flightbyte/mcp

Add --scope user to have it in every project. To share it with a team through a committed .mcp.json, keep the key in each person's environment:

{
  "mcpServers": {
    "flightbyte": {
      "type": "http",
      "url": "https://mcp.flightbyte.dev/mcp",
      "headers": { "Authorization": "Bearer ${FLIGHTBYTE_KEY}" }
    }
  }
}

Click Add to Cursor at the top for the hosted server, or this link for the local one, then replace YOUR_FLIGHTBYTE_KEY in the installed entry. Or add it to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "flightbyte": {
      "url": "https://mcp.flightbyte.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_FLIGHTBYTE_KEY" }
    }
  }
}

Local:

{
  "mcpServers": {
    "flightbyte": {
      "command": "npx",
      "args": ["-y", "@flightbyte/mcp"],
      "env": { "FLIGHTBYTE_KEY": "YOUR_FLIGHTBYTE_KEY" }
    }
  }
}

"Bearer ${env:FLIGHTBYTE_KEY}" also works, if Cursor was started from a shell that has the variable.

Click Install in VS Code at the top: VS Code asks for the key and stores it securely. Or add it to .vscode/mcp.json:

{
  "inputs": [
    { "type": "promptString", "id": "flightbyte_key", "description": "FlightByte API key", "password": true }
  ],
  "servers": {
    "flightbyte": {
      "type": "http",
      "url": "https://mcp.flightbyte.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:flightbyte_key}" }
    }
  }
}

Local, from a terminal:

code --add-mcp '{"name":"flightbyte","type":"stdio","command":"npx","args":["-y","@flightbyte/mcp"],"env":{"FLIGHTBYTE_KEY":"YOUR_FLIGHTBYTE_KEY"}}'

Add the local server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then quit and reopen Claude:

{
  "mcpServers": {
    "flightbyte": {
      "command": "npx",
      "args": ["-y", "@flightbyte/mcp"],
      "env": { "FLIGHTBYTE_KEY": "YOUR_FLIGHTBYTE_KEY" }
    }
  }
}

The hosted server can also be added under Settings → Connectors → Add custom connector with the URL https://mcp.flightbyte.dev/mcp. Sending the key needs the connector's Request headers option (authorization: Bearer YOUR_FLIGHTBYTE_KEY), which is in beta and not on every account; without it only the docs tools work, so the local server is the reliable choice here.

• Streamable HTTP: https://mcp.flightbyte.dev/mcp with the header Authorization: Bearer YOUR_FLIGHTBYTE_KEY (or x-api-key: YOUR_FLIGHTBYTE_KEY).

• stdio: command npx, arguments -y @flightbyte/mcp, environment FLIGHTBYTE_KEY=YOUR_FLIGHTBYTE_KEY.

Both speak MCP 2026-07-28 and the 2025 revisions (2024-11-05 to 2025-11-25); the client's first message picks one.

Configuration

Self-hosting

The hosted server is this repository's Dockerfile: a stateless Streamable HTTP server with no database and no secrets of its own.

docker build -t flightbyte-mcp .
docker run -p 8080:8080 flightbyte-mcp

It serves POST /mcp and GET /healthz. Each request gets a fresh server bound to the key in its headers; responses are plain JSON with no sessions, so it scales to any number of replicas. Requests in the 2026-07-28 format are served by the SDK's per-request handler, and 2025-era requests by a JSON-mode Streamable HTTP transport. Deployment notes for Dokploy are in DEPLOY.md.

Development

Running the server needs Node.js 20 or later; developing it needs 22.12 or later.

npm install
npm run build        # TypeScript → dist/
npm test             # builds, then runs everything against a local mock of the API and docs
npm run typecheck
npm run lint

The tests never touch the real API and need no key. They cover every tool's request mapping, the error mapping, docs parsing and ranking, and both transports end to end: the built dist/stdio.js and dist/http.js are spawned and driven by MCP clients on protocol 2025-11-25 and 2026-07-28, including one built on the v1 SDK. A drift check fails when a tool's parameter names, locations, required fields or enums stop matching spec/openapi.json, a copy of the public OpenAPI document. When the API changes:

npm run sync:openapi
npm test

Try it by hand with the MCP Inspector, or against a local API:

npx @modelcontextprotocol/inspector node dist/stdio.js

FLIGHTBYTE_API_URL=http://localhost:3000/v1 FLIGHTBYTE_KEY=your-local-key node dist/stdio.js

src/
  stdio.ts            bin entry: stdio transport, key from FLIGHTBYTE_KEY
  http.ts             HTTP entry: POST /mcp, GET /healthz, env config
  http-app.ts         request handling, protocol routing, key extraction, per-IP rate limit
  server.ts           createServer(): registers every tool on an McpServer
  tools/api-tools.ts  the 13 API tools, one definition per OpenAPI operation
  tools/docs-tools.ts search_docs and get_doc_page
  docs.ts             llms-full.txt parsing, ranking, caching, page fetches
  api.ts              fetch wrapper for the REST API
  errors.ts           error envelope → tool error with next steps
spec/openapi.json     copy of the public OpenAPI document (npm run sync:openapi)
server.json           MCP Registry entry: the npm package and the hosted remote

1. Bump version in package.json and in both places in server.json; a test fails if they differ.

2. npm publish. It runs typecheck, lint and tests first, and publishes publicly under the @flightbyte scope.

3. Publish server.json to the MCP Registry: mcp-publisher login dns --domain flightbyte.dev …, then mcp-publisher publish.

4. Redeploy the Docker image behind mcp.flightbyte.dev.

License

MIT