01
Aviation MCP is an aviation data service built on the Model Context Protocol, giving AI agents nine tools covering flight status, transfer options, comfort metrics, real-time position, airport weather and airfares. Any MCP-capable client or agent framework — Claude Code, Codex CLI, Cursor, Claude Desktop, or your own agent built on the official MCP SDKs — connects with a single URL.
Two transports are supported: MCP streamable HTTP (recommended — stateless, JSON responses, protocol version 2025-03-26, no local process required) and stdio via our official npm packages running locally. OAuth 2.1 (PKCE + Dynamic Client Registration) is also available for clients that support it.
02
Sign up, open the console and create a key on the API Keys page. New accounts receive ¥50 in trial credits — you can start calling without topping up. The key is shown in full only once at creation; store it safely. Create one in the console →
Pick your tool under Client Setup below and replace YOUR_API_KEY with your key. Once added, the client discovers all tools automatically.
Ask your agent in natural language — it will pick and combine the right tools on its own. Try this prompt:
What non-stop flights are there from Shanghai to Beijing tomorrow? Compare punctuality and comfort, then recommend the two best options with the current lowest fares.03
API key authentication is recommended (all configs below are tested against production). Clients that support the OAuth flow can also add the bare URL and sign in when prompted; access tokens last 1 hour and the client renews them automatically with a refresh token, so you don't need to sign in again. For unattended automation, use an API key.
One command in your terminal:
claude mcp add --transport http variflight-aviation https://ai.variflight.com/servers/aviation/mcp \
--header "X-API-Key: YOUR_API_KEY"Add to ~/.codex/config.toml (or use codex mcp add interactively):
[mcp_servers.variflight_aviation]
url = "https://ai.variflight.com/servers/aviation/mcp"
http_headers = { "X-API-Key" = "YOUR_API_KEY" }Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"variflight-aviation": {
"url": "https://ai.variflight.com/servers/aviation/mcp",
"headers": { "X-API-Key": "YOUR_API_KEY" }
}
}
}Bridge via mcp-remote in claude_desktop_config.json under mcpServers:
{
"mcpServers": {
"variflight-aviation": {
"command": "npx",
"args": [
"-y", "mcp-remote", "https://ai.variflight.com/servers/aviation/mcp",
"--header", "X-API-Key: YOUR_API_KEY"
]
}
}
}Call the streamable HTTP endpoint from any language (official MCP SDKs support remote HTTP servers, or speak JSON-RPC directly):
curl -X POST https://ai.variflight.com/servers/aviation/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'If you prefer local stdio transport, or your client doesn't support remote HTTP servers, use our official npm packages (@variflight-ai/variflight-mcp for Aviation, @variflight-ai/tripmatch-mcp for Tripmatch) — same toolset as the remote service:
{
"mcpServers": {
"variflight-aviation": {
"command": "npx",
"args": ["-y", "@variflight-ai/variflight-mcp"],
"env": { "VARIFLIGHT_API_KEY": "YOUR_API_KEY" }
}
}
}04
Parameters marked * are required. Airport/city codes are IATA 3-letter codes (cities like BJS, SHA; airports like PEK, PVG); dates use YYYY-MM-DD. Train tools take Chinese city and station names.
Flight-list and connecting-itinerary tools (searchFlightsByDepArr and getFlightTransferInfo in Aviation; searchFlightsByDepArr and getFlightAndTrainTransferInfo in Tripmatch) accept optional limit, offset and detail parameters, on the remote service and in the npm packages from version 1.1.0. limit caps the number of results; offset skips results for paging, using next_offset from the previous response; detail set to summary returns only the core fields, and full (the default) returns every field. When any of them is set, the response also includes total, offset, returned and next_offset; without them the response format is unchanged. Each page is billed as one call. When the remote service URL ends with ?profile=compact, these tools return the first 20 results in summary form by default.
Search non-stop flights by origin, destination and date (aircraft type, scheduled/actual times, check-in counters and more). Use depcity/arrcity for cities, dep/arr for airports — don't mix them on the same side.
date* dep|depcity arr|arrcity limit offset detail
Look up a flight by number (with airline code, e.g. MU2157) and date.
fnum* date* dep arr
Find connecting flight itineraries between two cities on a date.
depdate* depcity* arrcity* limit offset detail
Comfort details for a known flight: punctuality, seats and cabin, meals, entertainment, baggage allowance.
fnum* date* dep arr
Real-time aircraft position by registration (tail) number, e.g. B2021.
anum*
Returns today's date (computed locally — prevents the model from hardcoding dates).
—
3-day weather forecast for an airport by IATA code.
airport*
Natural-language itinerary summary of flights on sale between two cities (lowest fare, shortest duration, recommendations).
depCityCode* depDate* arrCityCode*
Structured fare data for flights on sale between two cities, per flight and per cabin.
dep_city* arr_city* dep_date*
05
Billing is in credits: 1 credit = ¥0.01 CNY. Each tool call deducts its listed price from your balance — bonus credits first (by expiry), then recharged balance.
Protocol-level calls (initialize, tools/list, etc.) and getTodayDate are free. Failed calls (upstream errors, timeouts) are not charged.
New accounts get ¥50 in trial credits. Top-ups earn a 4x bonus in usage credits (valid 30 days). Alipay and international cards (Stripe) are supported.
Calls are allowed while your total balance is above zero; once depleted, calls return 403 — top up in the console to resume.
06
Dates must be YYYY-MM-DD; airports/cities use IATA 3-letter codes. Have your agent call getTodayDate first and derive relative dates ("tomorrow", "next Friday") from it instead of hardcoding from memory.
Each tool call is capped at roughly 30 seconds. Flight lists and connecting itineraries on busy routes return large payloads; use the limit and detail parameters to keep them small, or connect to the ?profile=compact URL.
Failed tool executions return text content starting with "Error executing tool" rather than a protocol-level error; agents generally recognize this and retry with corrected parameters.
Your key spends your balance. Never commit it to public repos or ship it in frontend code. If leaked, revoke and recreate it in the console immediately.
OAuth 2.1 (authorization code + PKCE + Dynamic Client Registration) is available for clients that support it. Access tokens last 1 hour; on expiry the client exchanges its refresh token for a new one. Refresh tokens last 30 days and are replaced on each renewal, so re-authorization is needed only after 30 days without use. For unattended automation, use an API key.
401 means the API key is missing or invalid — check the X-API-Key header and verify the key on the console Keys page. 403 usually means insufficient balance (top up on the Billing page), or the key/account has been disabled. Error messages include the specific reason and a link to resolve it.