AI agents

MCP (AI agents)

Connect Claude and other AI assistants to 1fly with the Model Context Protocol, so they can book flights under the same rules as your code.

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools in a uniform way. The 1fly MCP server turns the 1fly API into tools an agent can use: create an order, follow it, handle a price change, and in test mode simulate the payment.

The server is a thin, stateless layer. Each tool call is forwarded to the API with your API key, so the agent has exactly the scopes of that key, its calls count towards your plan, and every call shows up in your request log with channel: mcp and the tool name.

Connect#

Transport Address
Streamable HTTP http://localhost:4100/mcp (send your key in the Authorization header on every request)
stdio Run apps/mcp/dist/stdio.js with ONEFLY_API_KEY in the environment

Claude Code#

Shell
claude mcp add --transport http 1fly http://localhost:4100/mcp --header "Authorization: Bearer 1fly_test_…"

Requests without a well-formed key are refused with 401.

stdio (Claude Desktop, Cursor and other local clients)#

JSON
{
  "mcpServers": {
    "1fly": {
      "command": "node",
      "args": ["/absolute/path/to/1fly/apps/mcp/dist/stdio.js"],
      "env": {
        "ONEFLY_API_KEY": "1fly_test_…",
        "ONEFLY_API_URL": "http://localhost:4000"
      }
    }
  }
}

Tools#

ToolWhat it doesScope
find_airportsFinds airports by city, airport name or IATA code (English, Russian or Uzbek) and returns their 3-letter codes.search:read
search_flightsSearches flights for a route, date(s) and passenger mix across all airlines and returns a ranked, compact list of offers (airline, flights with local times, duration, stops, total price in minor units, baggage, refundability) with an offerId each.search:read
get_search_resultsReturns the offers of an earlier search_flights call: more results while it is still running (waitSeconds lets the server wait), another sort order ("best", "cheapest", "fastest") or the next page (offset).search:read
get_offerReturns one offer in full: every flight with local times, the passenger mix it was priced for, the date passenger ages are judged on, the price breakdown and the fare options (e.g.search:read
get_fare_optionsLists the fare options (brands) of an offer with their conditions: price for all passengers, hand and checked baggage, refund policy and fee, change policy and fee; marks the cheapest.search:read
get_fare_rulesReturns the fare rules of an offer in plain words, per fare option: baggage, refund, changes and void.search:read
create_orderBooks a flight for the given passengers and starts the booking: price re-check, seat hold, then payment.orders:write
get_orderReturns one order: status, route, price, passengers (passport numbers masked), payments, tickets and the live booking state (new price, pay URL, hold expiry, whether it waits for issue_order).orders:read
get_order_timelineExplains what happened to an order step by step (check passengers, re-check price, hold seats, payment, issue ticket, send e-ticket, void): each step’s state, number of attempts and the last error code with a hint on what to do.orders:read
list_ordersLists this account’s orders, newest first, optionally filtered by status.orders:read
decide_price_changeAnswers a price change for an order in status awaiting_price_confirmation.orders:write
cancel_orderCancels an order that is not ticketed: before payment (validating, price_check, awaiting_price_confirmation, booking, awaiting_payment), or a manual-issue order paid and waiting for issue_order.orders:write
simulate_paymentTEST MODE ONLY. Test mode only.orders:write
issue_orderIssues the tickets of an order created with issue: "manual".orders:issue
void_orderVoids the tickets of an issued order and refunds the payment in full.orders:issue
get_usageShows the account this API key belongs to, its plan limits (orders per month, requests per minute, live keys) and usage in the current period.None
list_request_logsLists recent API requests of this account, newest first: method, path, status, error code, duration, channel (api, mcp, utcp, web) and agent tool.logs:read

The server also exposes a resource, 1fly://docs/booking-flow, describing statuses and what an agent should do in each, and a prompt, book_flight, that walks an assistant through collecting passenger data and confirming before booking.

Create a dedicated key for each agent at http://localhost:3000/app/api-keys:

Agent does Scopes
Answers questions about existing orders orders:read
Books, handles price changes, cancels orders:read, orders:write
Also debugs its own failed calls add logs:read

Use a test key while you develop. Give the key an expiry, and revoke it when the agent is retired. A separate key per agent keeps its traffic separate in the request log and its rate limit separate from your servers.

Safety#

  • Idempotency. create_order accepts an idempotencyKey. When the agent leaves it out, the server derives one from the input (mcp- plus a SHA-256 of the canonical JSON), so a retried tool call with the same input returns the existing order instead of booking twice.
  • Human approval. decide_price_change and cancel_order are marked destructive; MCP clients that honour tool annotations ask the user before running them. Configure your client so that create_order also needs approval, and have the agent read the booking back to the traveller before calling it. The book_flight prompt does this.
  • Price changes. Only a person may accept a higher price. The agent should show the old and new total and wait for an explicit answer.
  • Strict inputs. Unknown fields are rejected, and inputs are checked locally with the same rules as the API before anything is sent, so the agent gets every problem at once as path: message.
  • Test-only payment. simulate_payment refuses live orders and works only while an order is awaiting_payment.
  • Polling. Agents should call get_order no more than every 2–3 seconds while waiting.
API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)