1. 文档概览

本文档介绍航班管家 MCP 数据平台开放能力的接入方式、能力说明、计费规则、工具调用及客户端配置方式，帮助开发者快速完成 MCP 接入、能力调用与问题排查。

2. 快速开始

建议开发者先完成账号、Key、余额与 MCP 网关地址确认，再接入工具调用。

3. 能力说明

平台对外提供 9 个 MCP 数据能力工具（含实时查询与报表类 Excel）。能力说明用于帮助开发者快速了解每个能力的用途、对应工具标识与调用方式。

3.1 字段详情

下列字段用于说明各能力返回数据的大致范围。字段详情默认折叠展示，展开后可查看对应能力包含的字段。

4. 计费说明

平台采用账户余额预付费模式。用户充值后，成功调用 MCP 能力按次扣减余额；调用失败不扣费；余额不足时能力调用失败并返回余额不足提示。

5. 航班管家 MCP 开发者文档

本文档面向开发者，涵盖两大块：

1. MCP 开放服务 —— 提供航班动态、机场对查询、舒适度、延误预测、天气、轨迹及报表类（每日总览 / 机场运行 / 航司运行）共 9 项数据工具，支持业务开发调用，也可直接配置至 AI 客户端。
2. AI 客户端接入 —— 在 Claude（Claude Desktop、Claude Code） / VS Code 扩展（Codex、Cline） / Cursor / Trae 中配置使用。

5.1 MCP 开放服务

5.1.1 接入前准备

5.1.1.1 统一接入域

MCP 服务统一端点格式：${MCP_GATEWAY_HOST}/mcp/{serverCode}，当前对接的 serverCode 为 dast_mcp，即完整地址：

https://fly.huoli.com/mcp/dast_mcp

5.1.1.2 权限与凭证

• 面向 dast 平台注册用户：注册登录后前往个人中心 MCP 控制台创建 API Key。
• 数据接口按次计费，从 dast 账户余额扣减。

5.1.1.3 支持能力速览（9 个工具）

5.1.2 协议与鉴权

5.1.2.1 协议

• 协议：MCP（Model Context Protocol），采用 Streamable‑HTTP 作为传输层
• HTTP 方法：POST
• Content-Type：application/json
• 编码：UTF-8

5.1.2.2 鉴权

请求 Header：

Authorization: Bearer <您的 dast API Key>
Content-Type: application/json

5.1.2.3 stdio 桥接兼容模式

针对仅支持 stdio 的 AI 客户端，点击链接访问 NPM 桥接包，内含完整接入指引：https://www.npmjs.com/package/@flightmaster/aviation-dast-mcp

5.1.3 初始化握手（initialize）

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
  -H 'Authorization: Bearer <替换为您的 dast API Key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "Your-Client",
        "version": "1.0.0"
      }
    }
  }'

成功返回：

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "version": "2.0.0",
      "name": "mcp-gateway"
    }
  },
  "id": 1
}

5.1.4 列出工具（tools/list）

首次接入或需要确认可用工具时调用。AI 客户端接入时也是通过该方法自动发现全部工具。

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
  -H 'Authorization: Bearer <替换为您的 dast API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

返回示例（节选）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "dast_flight_dynamic",
        "description": "按航班号查询指定日期的航班全量动态数据……",
        "inputSchema": {
          "type": "object",
          "properties": {
            "fnum": { "type": "string", "description": "航班号，必填（如CA1831）" },
            "date": { "type": "string", "description": "飞行日期，必填，格式：YYYY-MM-DD" }
          },
          "required": ["fnum", "date"]
        }
      },
      {
        "name": "dast_flight_route",
        "description": "按起降机场三字码查询指定日期的航线航班动态数据……",
        "inputSchema": {
          "type": "object",
          "properties": {
            "depCode": { "type": "string", "description": "出发机场三字码，必填" },
            "arrCode": { "type": "string", "description": "到达机场三字码，必填" },
            "date":    { "type": "string", "description": "飞行日期，必填，格式：YYYY-MM-DD" }
          },
          "required": ["depCode", "arrCode", "date"]
        }
      }
    ]
  }
}

网关会返回全部 9 个工具的 name / description / inputSchema，开发者可直接消费该协议驱动 AI 客户端自动选择工具。

5.1.5 调用工具（tools/call）

5.1.5.1 通用请求格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "工具标识",
    "arguments": { ...入参键值对... }
  }
}

5.1.5.2 统一返回格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"code\":0,\"msg\":\"success\",\"data\":...}"
      }
    ],
    "isError": false
  }
}

业务数据以 JSON 字符串放在 result.content[0].text 中，解析后结构统一为：

{
  "code": 0,
  "msg": "success",
  "data": { ... },
  "count": 1
}

5.1.5.3 工具调用示例（9 个）

以下示例均以 Bearer sk_phone_xxx 调用 https://fly.huoli.com/mcp/dast_mcp。

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_flight_dynamic","arguments":{"fnum":"CA1831","date":"2026-08-10"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": [
                            {
                            "flightNo": "CA1831",
                            "depAirport": "北京首都",
                            "arrAirport": "上海虹桥",
                            "flightState": "到达",
                            "depPlanTime": "2026-08-10 07:30:00",
                            "arrPlanTime": "2026-08-10 09:45:00"
                            }
                            ],
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_flight_route","arguments":{"depCode":"PEK","arrCode":"SHA","date":"2026-08-10"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": [
                            {
                            "flightNo": "CA1831",
                            "depAirport": "北京首都",
                            "arrAirport": "上海虹桥",
                            "depPlanTime": "2026-08-10 07:30:00",
                            "arrPlanTime": "2026-08-10 09:45:00",
                            "depTerminal": "T3",
                            "arrTerminal": "T2",
                            "aircraftType": "330",
                            "depOntimeRate": "0.85",
                            "checkInTable": "H01-H08",
                            "flightProperty": "国内",
                            "serviceType": "正班",
                            "flightState": "到达",
                            "shareFlag": "0",
                            "mainFlightNo": "CA1831"
                            }
                            ],
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_flight_happy","arguments":{"fnum":"9C8672","date":"2026-08-15","cabin":"Y"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": [
                            {
                            "flightNo": "9C8672",
                            "depAirport": "上海浦东",
                            "arrAirport": "深圳宝安",
                            "cabins": [
                            {
                            "cabin": "Y",
                            "cabinName": "经济舱"
                            }
                            ]
                            }
                            ],
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_future_weather","arguments":{"airport":"HFE"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": {
                            "airportCity": "合肥",
                            "airportName": "合肥新桥国际机场",
                            "weatherHourly": [
                            {
                            "weatherType": "晴",
                            "windPower": "3级",
                            "windSpeed": "4.2",
                            "windDirection": "45",
                            "rh": "78",
                            "prec": "0",
                            "pressure": "1008",
                            "clouds": "60"
                            }
                            ],
                            "maxTemperature": "33",
                            "minTemperature": "24",
                            "avgTemperature": "28.5"
                            },
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_flight_path","arguments":{"fnum":"CZ3000","depCode":"PEK","arrCode":"CAN","date":"2026-08-06"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": {
                            "aircraftNo": "B-1234",
                            "flightNo": "CZ3000",
                            "depAirport": "北京首都",
                            "arrAirport": "广州白云",
                            "curLat": "40.078538",
                            "curLon": "116.5871",
                            "curSpeed": "420",
                            "curHeight": "10668",
                            "curAngle": "180",
                            "aircraftType": "330",
                            "aircraftAge": "5",
                            "airlineCompany": "中国南方航空",
                            "flightState": "到达",
                            "depPlanTime": "2026-08-06 08:00:00",
                            "arrPlanTime": "2026-08-06 11:20:00"
                            },
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_delay_rate","arguments":{"fnum":"CZ3000","depCode":"PKX","arrCode":"CAN","date":"2026-08-10"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": {
                            "delayRate_30min": "0.1220",
                            "delayRate_60min": "0.0255",
                            "delayRate_90min": "0.0451",
                            "cancelRate": "0.4336"
                            },
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_flight_overview_daily","arguments":{"date":"2026-08-10"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": {
                            "file_url": "https://data-api.133.cn/mcp/v1/flight/statistics/airportDaily/export?order_no=0123456789abcdef0123456789abcdef",
                            "expires_at": "2026-01-01 23:59:59"
                          },
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_airport_operation_statistics","arguments":{"airport":"PEK","start_time":"2026-08-01","end_time":"2026-08-07","route_type":"all"}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": {
                            "file_url": "https://data-api.133.cn/mcp/v1/airport/statistics/export?order_no=0123456789abcdef0123456789abcdef",
                            "expires_at": "2026-01-01 23:59:59"
                            },
                            "count": 1
                            }

curl -X POST 'https://fly.huoli.com/mcp/dast_mcp' \
                            -H 'Authorization: Bearer <替换为您的 dast API Key>' \
                            -H 'Content-Type: application/json' \
                            -d
                            '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dast_airline_operation_statistics","arguments":{"airline":"CA","start_time":"2026-08-01","end_time":"2026-08-07","passenger":1}}}'

{
                            "code": 0,
                            "msg": "success",
                            "data": {
                            "file_url": "https://data-api.133.cn/mcp/v1/airline/statistics/export?order_no=0123456789abcdef0123456789abcdef",
                            "expires_at": "2026-01-01 23:59:59"
                            },
                            "count": 1
                            }

5.1.5.4 入参速查汇总

5.1.6 错误码

5.1.6.1 网关层错误

5.1.6.2 业务层（text 内 code）

常见业务 msg：

• 用户不存在：Key 绑定的 dast 身份未建立
• MCP账户余额不足：需在 dast 个人中心充值
• date 仅支持当日至未来15天：查询日期越界
• 上游接口返回失败：数据源异常，稍后重试

5.2 AI 客户端接入 MCP 服务

5.2.1 主流 AI 客户端接入示例

接入前请先确认：已在 dast 平台注册登录、已获取 API Key（sk_phone_xxx）。

5.2.1.1 Claude（Claude Desktop / Claude Code）

Claude 支持标准 MCP Streamable HTTP 接入：只需注册一次 Server 端点，Claude 会自动调用 tools/list 拉取全部工具，无需逐个手动声明。

Claude Code（命令行）：

claude mcp add --transport http dast-huoli https://fly.huoli.com/mcp/dast_mcp \
  --header "Authorization: Bearer <替换为您的 dast API Key>"

Claude Desktop / Claude Code（配置文件）：在 claude_desktop_config.json（或 Claude Code 的 MCP 配置）中添加：

{
  "mcpServers": {
    "dast-huoli": {
      "type": "http",
      "url": "https://fly.huoli.com/mcp/dast_mcp",
      "headers": {
        "Authorization": "Bearer <替换为您的 dast API Key>"
      }
    }
  }
}

保存后 Claude 会自动调用 tools/list 拉取全部工具；后续网关新增工具，客户端重新加载配置即可自动发现，无需改动以下配置。

5.2.1.2 Cursor

在项目根目录 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "dast-huoli": {
      "type": "http",
      "url": "https://fly.huoli.com/mcp/dast_mcp",
      "headers": {
        "Authorization": "Bearer <替换为您的 dast API Key>"
      }
    }
  }
}

保存后 Cursor 会自动调用 tools/list 拉取全部工具；后续新增工具也无需改动配置。

5.2.1.3 VS Code扩展（Codex / Cline）

Cline / Codex 均支持标准 MCP Streamable HTTP 接入，注册一次端点后自动调用 tools/list 拉取全部工具，无需逐个手动声明。

Cline：在项目根目录 .vscode/mcp.json 中添加：

{
  "servers": {
    "dast-huoli": {
      "type": "http",
      "url": "https://fly.huoli.com/mcp/dast_mcp",
      "headers": {
        "Authorization": "Bearer <替换为您的 dast API Key>"
      }
    }
  }
}

Codex：在 ~/.codex/config.toml 中添加：

[mcp_servers.dast-huoli]
type = "http"
url = "https://fly.huoli.com/mcp/dast_mcp"
headers = { Authorization = "Bearer <替换为您的 dast API Key>" }

保存后 Cline / Codex 会自动调用 tools/list 拉取全部工具；后续新增工具也无需改动配置。

5.2.1.4 Trae IDE

在 Trae 的 MCP 配置文件（设置 → MCP Servers → 编辑配置）中添加：

{
  "mcpServers": {
    "dast-huoli": {
      "name": "航班管家航空数据",
      "description": "航班动态、舒适度、延误预测、未来天气、飞行轨迹",
      "type": "http",
      "endpoint": "https://fly.huoli.com/mcp/dast_mcp",
      "headers": {
        "Authorization": "Bearer <替换为您的 dast API Key>",
        "Content-Type": "application/json"
      }
    }
  }
}

保存后 Trae 会自动调用 tools/list 拉取全部 9 个工具。如 Trae 版本要求手动声明工具，可按本文档第四节的 tools/call 请求格式逐个声明。

5.3 官方 GitHub 仓库

Flight Master DAST 已建立官方 GitHub 开发者仓库，用于发布航班管家航空数据 MCP 的官方说明、接入示例及相关开发资源。

官方仓库：https://github.com/flight-master-dast/aviation-data-mcp

6. Agent 文档

为 AI Agent 提供航班管家 MCP 能力、接入方式及工具调用规则的机器可读文档。

文档地址： https://dast.133.cn/mcp_assets/agent.md