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?"

In Claude (claude.ai, Desktop or mobile) there is nothing to copy: FlightByte is in Claude's connector directory. Add it there, and the first time Claude needs your account it asks you to sign in to FlightByte and allow it. See Sign in with OAuth.

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

Related MCP server: FlightTicketMCP

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. Signed in with OAuth, the app never sees a key at all, and you can revoke it under Connected apps.

• 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 a secret yourself with the API: reveal, rotate.

• 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; a 402 overage_cap_reached says the cap you set on extra flights is reached and where to raise or remove it.

• 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" }
    }
  }
}

Or skip the key: add FlightByte from Claude's connector directory, or add the hosted server under Customize → Connectors → Add custom connector with the URL https://mcp.flightbyte.dev/mcp (on Team and Enterprise plans an Owner adds it under Organization settings → Connectors). If the dialog asks, pick Sign in when needed and Use Claude's published identity. The docs tools work right away; the first time Claude calls a tool that needs your account, it shows a Connect button, you sign in to FlightByte and allow it, and the call goes through. See Sign in with OAuth.

• 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. A Streamable HTTP client that supports MCP authorization can sign in with OAuth instead of sending a key.

Sign in with OAuth

The hosted server is an OAuth 2.1 protected resource, as the MCP authorization spec describes, so clients that take OAuth and no API key (Claude's connectors) can use it with your account.

• Signed out, initialize, tools/list, search_docs and get_doc_page work. Calling an API tool answers 401 with WWW-Authenticate: Bearer resource_metadata="https://mcp.flightbyte.dev/.well-known/oauth-protected-resource/mcp", which is what makes the client offer to sign in.

• The authorization server is the FlightByte API (https://api.flightbyte.dev, metadata at /.well-known/oauth-authorization-server). You sign in to the dashboard and allow the app there; it acts as one of your API keys, so that key's plan, quota, logs and watched flights apply. Clients identify themselves with a Client ID Metadata Document (as Claude and Claude Code do) or register dynamically; PKCE is required, and refresh tokens rotate.

• Scopes: flights:read (the flight tools), subscriptions:read (listing watches, deliveries and events) and subscriptions:write (creating, changing and deleting watches, and test events). A tool outside the granted scopes answers 403 insufficient_scope.

• Tokens are never passed through. The MCP spec forbids sending a client's token on to another API, so this server trades it at the authorization server (RFC 8693) for a short-lived token for the API, with a client secret of its own, and keeps the trade in memory until it expires. Revoking the app under Connected apps, or revoking the key it acts as, stops it on its next request.

• API keys work exactly as before, in either header. OAuth is off unless FLIGHTBYTE_OAUTH_CLIENT_SECRET is set.

Configuration

Self-hosting

The hosted server is this repository's Dockerfile: a stateless Streamable HTTP server with no database. Its one secret is the OAuth client secret, and only when OAuth is on.

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, the OAuth gate, per-IP rate limit
  oauth.ts            protected resource metadata, WWW-Authenticate challenges, the token trade
  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