> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollinggo.store/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

# RollingGo MCP — 5分钟快速接入指南 (v1.0)

**更新于：2026-08-12** | **文档版本：v1.0**

> **面向：** 第三方开发者、AI Agent 构建者、MCP 客户端用户\
> **目标：** 5 分钟内完成第一次 RollingGo MCP 接入，获取全球酒店搜索与预订能力（注：机票业务已下线维护）

***

## ⚡ 30 秒概览

RollingGo 提供两类 [Model Context Protocol(MCP)](https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro) 服务：

| 服务 | 端点 | 已上线 Tool | 状态 | 认证方式 |
| :- | :- | :- | :-: | :- |
| **酒店 MCP** | `https://mcp.rollinggo.cn/mcp` | `searchHotels` / `getHotelDetail` / `getHotelSearchTags` (共 3 个) | ✅ **正常运营** | `Authorization: Bearer YOUR_API_KEY` |
| **机票 MCP** | `https://mcp.rollinggo.cn/mcp/flight` | `searchAirports` / `searchFlights` (共 2 个) | ⚠️ **已下线** | `Authorization: Bearer YOUR_API_KEY` |

> ⚠️ **业务变更说明**：机票 MCP 业务 (`searchAirports` / `searchFlights`) 目前已暂停下线维护。推荐使用并接入主推的酒店 MCP 服务。以下配置与示例保留供参考。

**传输协议：** `streamable-http` / `http`

***

## 🚀 快速接入步骤

### 第一步：选择身份注册

1. 访问 [https://rollinggo.store/apply](https://rollinggo.store/apply)
2. 根据你的使用场景选择 **四大业务身份卡片** 之一：
   * **开发者 (Developer)**：已有或正在开发智能体/旅行程序，接入 MCP 服务（推荐开发者使用）
   * **企业 (Enterprise)**：企业主体申请接入，面向企业员工差旅或外部客户
   * **个人 (Personal)**：使用个人 AI 工具（OpenClaw / Claude Code / Codex / Cursor / WorkBuddy 等）极速免账号体验
   * **达人分销 (KOL)**：有推广渠道，通过 H5 / 小程序进行分销变现
3. 选择所属服务区域：
   * **中国大陆**：绑定 `rollinggo.cn` 节点与人民币 (CNY) 结算
   * **海外及港澳台**：绑定 `rollinggo.ai` 节点与美元 (USD) 结算

***

### 第二步：获取APIKEY

1. **全员秒级过审**：Partner 2.0 支持系统自动秒过，无任何人工审核卡点。
2. **页面即时下发**：提交后前端页面直接展示 32 位 API Key（格式：`mcp_xxxxx...`），可一键复制。
3. **查收登录邮件**：
   * 开发者 / 企业主体系统自动创建 Partner 后台账户，初始密码自动发送至预留邮箱。
   * 登录伙伴中心后台可配置加价比例、查看流量日志、查询订单与收益。
   * 个人 C 端用户免创建后台账号，直接获取安装指令与配置资源。
4. 将 API Key 保存好，后续所有 MCP 调用均需在 Header 中携带。

> 💡 **提示：** 提交成功页面及确认邮件中会提供完整 MCP 客户端 JSON 配置模板，可直接复制使用。

***

### 第三步：接入 Agent 工具

> 推荐 **Claude CLI**、**Codex**、**Cursor** 三个客户端。其他支持 MCP 的客户端（如 Kiro、豆包、Dify 等）配置方式类似。

#### 1. Claude CLI / Claude Desktop

在项目根目录创建 `.mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "RollingGo-Hotel": {
      "url": "https://mcp.rollinggo.cn/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    },
    "RollingGo-Flight": {
      "url": "https://mcp.rollinggo.cn/mcp/flight",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

也可以通过 CLI 命令行直接添加：

```bash theme={null}
claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  RollingGo-Hotel \
  https://mcp.rollinggo.cn/mcp
```

```bash theme={null}
# ⚠️ 注意：机票 MCP 当前已下线维护
claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  RollingGo-Flight \
  https://mcp.rollinggo.cn/mcp/flight
```

#### 2. Codex

配置文件位置：`项目根目录/.codex/config.json` 或全局 `~/.codex/config.json`：

```json theme={null}
{
  "mcpServers": {
    "RollingGo-Hotel": {
      "url": "https://mcp.rollinggo.cn/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    },
    "RollingGo-Flight": {
      "url": "https://mcp.rollinggo.cn/mcp/flight",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

#### 3. Cursor

配置文件位置：`项目根目录/.cursor/mcp.json` 或全局 `~/.cursor/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "RollingGo-Hotel": {
      "url": "https://mcp.rollinggo.cn/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    },
    "RollingGo-Flight": {
      "url": "https://mcp.rollinggo.cn/mcp/flight",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

> 将 `YOUR_API_KEY` 替换为你收到的实际 API Key。酒店和机票使用相同的认证方式，区别仅在于 URL（`/mcp` vs `/mcp/flight`）。（⚠️ 注：机票 MCP 目前已下线维护）。

#### 4. cURL 直接测试

> ⚠️ **注意：** cURL 必须带 `-H "Accept: application/json, text/event-stream"` 请求头，否则服务端会返回 400。

```bash theme={null}
curl -X POST https://mcp.rollinggo.cn/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "searchHotels",
      "arguments": {
        "originQuery": "上海外滩五星酒店",
        "place": "上海外滩",
        "placeType": "景点",
        "checkInParam": {
          "checkInDate": "2026-08-15",
          "stayNights": 2
        },
        "filterOptions": {
          "starRatings": [5.0]
        },
        "size": 3
      }
    },
    "id": 1
  }'
```

***

### 第四步：第一次 MCP 调用

配置完成后，对你的 AI 助手输入指令：

> **“帮我搜一下上海外滩附近后天入住的五星酒店”**

AI 会自动调用 `searchHotels` Tool，返回酒店列表。

#### 1. 酒店搜索请求示例

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "searchHotels",
    "arguments": {
      "originQuery": "上海外滩五星酒店",
      "place": "上海外滩",
      "placeType": "景点",
      "checkInParam": {
        "checkInDate": "2026-08-15",
        "stayNights": 2
      },
      "filterOptions": {
        "starRatings": [5.0]
      },
      "size": 3
    }
  },
  "id": 1
}
```

#### 2. 机票查询示例（⚠️ 已下线归档）

> ⚠️ **说明**：机票业务目前已下线维护，以下示例仅供历史记录参考。

##### Step 1：搜索机场，获取城市代码

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "searchAirports",
    "arguments": {
      "keyword": "杭州"
    }
  },
  "id": 1
}
```

##### Step 2：使用城市代码查询航班

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "searchFlights",
    "arguments": {
      "adultNumber": 1,
      "childNumber": 0,
      "cabinGrade": "ECONOMY",
      "tripType": "ONE_WAY",
      "fromCity": "HGH",
      "toCity": "CTU",
      "fromDate": "2026-08-15"
    }
  },
  "id": 1
}
```

***

### 第五步：查看结果与响应示例

#### 1. 酒店搜索示例数据 (`searchHotels`)

##### 表格渲染示例

| 酒店名称 | 星级 | 评分 | 距离地标 | 参考最低价 |
| :- | :-: | :-: | :-: | :-: |
| **上海和平饭店** (Fairmont Peace Hotel) | 5.0 | 4.9 | 124m (距外滩) | ¥4,665 / 晚 |
| **上海半岛酒店** (The Peninsula Shanghai) | 5.0 | 4.9 | 252m (距外滩) | ¥6,770 / 晚 |

##### 预期响应 JSON 结构示例

```json theme={null}
{
  "message": "酒店搜索成功",
  "hotelInformationList": [
    {
      "hotelId": 29529,
      "name": "上海和平饭店(Fairmont Peace Hotel on the Bund)",
      "brand": "费尔蒙",
      "address": "南京东路20号",
      "distanceInMeters": 124,
      "starRating": 5.0,
      "score": 4.9,
      "price": {
        "hasPrice": true,
        "currency": "CNY",
        "lowestPrice": 4665.0,
        "message": "查价成功。最低价格：4,665，币种：CNY"
      },
      "bookingUrl": "https://rollinggo.cn/pages/hotel/detail/index?id=29529",
      "hotelAmenities": ["酒吧", "健身房", "泳池", "SPA服务", "停车场", "WIFI"],
      "tags": ["SPA服务", "奢华度假", "运动友好酒店"]
    }
  ]
}
```

#### 2. 机票查询示例数据（⚠️ 已下线归档）

##### 表格渲染示例

| 航班号 | 航空公司 | 航线 | 时间 | 舱位类型 | 实时价格 |
| :- | :- | :- | :- | :-: | :-: |
| **CA1741** | 中国国际航空 | 杭州萧山 (HGH) → 成都天府 (CTU) | 07:40 - 10:40 | 经济舱 | ¥2,869 |
| **CZ6198** | 中国南方航空 | 杭州萧山 (HGH) → 武汉天河 (WUH) | 13:10 - 15:00 | 经济舱 | ¥4,631 |
| **CA3338** | 中国国际航空 | 杭州萧山 (HGH) → 深圳宝安 (SZX) | 12:55 - 15:15 | 经济舱 | ¥5,341 |

##### 预期响应 JSON 结构示例

```json theme={null}
{
  "success": true,
  "message": "航班查询成功",
  "flights": [
    {
      "flightNo": "CA1741",
      "airline": "中国国际航空",
      "fromAirport": "HGH",
      "toAirport": "CTU",
      "departureTime": "2026-08-15 07:40:00",
      "arrivalTime": "2026-08-15 10:40:00",
      "cabinGrade": "ECONOMY",
      "price": 2869.0,
      "currency": "CNY"
    }
  ]
}
```

***

## 📚 附录与进阶指南

### 💡 推荐调用流程 (v1.0)

#### 1. 酒店搜索

1. 用户说“帮我订酒店”。
2. 调用 `getHotelSearchTags` → 引导用户选择偏好（五星 / 泳池 / 含早 / 可取消）。
3. 调用 `searchHotels` → 返回候选酒店列表。
4. 用户选定 → 调用 `getHotelDetail` → 返回房型和价格（仅供展示与参考）。

#### 2. 机票查询（⚠️ 已下线）

1. 调用 `searchAirports` → 获取城市代码。
2. 调用 `searchFlights` → 返回航班列表。（注：机票服务目前已下线维护）

***

## ❓ 常见问题 (FAQ)

### Q1：配置后客户端看不到 Tool

1. 检查 `.mcp.json` / `config.json` 的语法是否正确。
2. 确认 `url` 和 `type` 是否匹配服务端要求。
3. 确认 `Authorization` header 中的 API Key 是否填写正确。
4. **保存配置后需重启 Agent 客户端生效**。

### Q2：返回 401 Unauthorized

API Key 无效或格式不全：

1. 确认 API Key 包含了前缀 `mcp_`。
2. `Authorization: Bearer YOUR_API_KEY` 中 `Bearer` 后面需包含空格。
3. 检查环境变量或配置文件中是否有首尾多余的换行符。

### Q3：返回 400 Bad Request

cURL 直接调用时常见，必须包含 `Accept` 请求头：

```bash theme={null}
-H "Accept: application/json, text/event-stream"
```

### Q4：searchHotels 返回空结果

1. 检查 `place` 和 `placeType` 是否匹配（如“上海外滩”设为“景点”）。
2. 适当放宽筛选条件（如删减星级或强性标签限制）。
3. 确认 `checkInDate` 为未来日期。

### Q5：searchFlights / 机票接口报错？

机票 MCP 服务 (`/mcp/flight`) 目前已暂停下线维护。若尝试调用会返回 404 或下线提示，请接入酒店 MCP 服务。

### Q6：价格和实际不一致？

搜索结果中的价格是参考价，实时价格可能有变动。初级版本（v1.0）仅支持信息查询与展示，暂不支持在线下单。

### Q7：如何免费获取 API Key？

前往 [https://rollinggo.store/apply](https://rollinggo.store/apply) 选择身份提交申请，秒级自动审核过审，前端页面即时展现 API Key。

***

## 📋 接入门槛与限制表

| 项目 | 说明 |
| :- | :- |
| **是否需要注册** | 是，在 Partner 2.0 平台选择四大身份申请 |
| **认证要求** | 统一需要 Header：`Authorization: Bearer API_KEY` |
| **调用频次限制** | 无限制 |
| **接口费用** | 完全免费 |
| **审核周期** | 全员秒级自动过审 (0等待) |
| **覆盖范围与币种** | 全球酒店（中国节点使用 CNY，海外节点使用 USD；机票业务已下线） |
| **下单能力** | v1.0 初级版本仅支持查询，暂不支持在线下单 |

***

## 📞 联系与支持

| 渠道 | 链接 / 联系方式 |
| :- | :- |
| **API Key 申请** | [https://rollinggo.store/apply](https://rollinggo.store/apply) |
| **技术支持** | 访问 [rollinggo.store](https://rollinggo.store)，扫描网页客服二维码入群 |
| **商务合作** | [contact@rollinggo.cn](mailto:contact@rollinggo.cn) / [contact@rollinggo.ai](mailto:contact@rollinggo.ai) |
| **伙伴中心** | [https://partner.rollinggo.cn](https://partner.rollinggo.cn) / [partner.rollinggo.ai](https://partner.rollinggo.ai) |
| **Skill Hub** | [https://rollinggo.store/solutions/skills](https://rollinggo.store/solutions/skills) |
| **GitHub 仓库** | [https://github.com/RollingGo-AI/rollinggo-readme](https://github.com/RollingGo-AI/rollinggo-readme) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.