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#
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)#
{
"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#
| Tool | What it does | Scope |
|---|---|---|
find_airports | Finds airports by city, airport name or IATA code (English, Russian or Uzbek) and returns their 3-letter codes. | search:read |
search_flights | Searches 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_results | Returns 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_offer | Returns 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_options | Lists 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_rules | Returns the fare rules of an offer in plain words, per fare option: baggage, refund, changes and void. | search:read |
create_order | Books a flight for the given passengers and starts the booking: price re-check, seat hold, then payment. | orders:write |
get_order | Returns 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_timeline | Explains 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_orders | Lists this account’s orders, newest first, optionally filtered by status. | orders:read |
decide_price_change | Answers a price change for an order in status awaiting_price_confirmation. | orders:write |
cancel_order | Cancels 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_payment | TEST MODE ONLY. Test mode only. | orders:write |
issue_order | Issues the tickets of an order created with issue: "manual". | orders:issue |
void_order | Voids the tickets of an issued order and refunds the payment in full. | orders:issue |
get_usage | Shows 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_logs | Lists 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.
Recommended scopes#
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_orderaccepts anidempotencyKey. 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_changeandcancel_orderare marked destructive; MCP clients that honour tool annotations ask the user before running them. Configure your client so thatcreate_orderalso needs approval, and have the agent read the booking back to the traveller before calling it. Thebook_flightprompt 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_paymentrefuses live orders and works only while an order isawaiting_payment. - Polling. Agents should call
get_orderno more than every 2–3 seconds while waiting.