> ## 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.

# MCP接入差异：API Key与OAuth 2.0 授权码模式

# RollingGo MCP 接入方式说明

RollingGo MCP 提供两种接入模式，以满足不同业务场景和项目阶段的需求：

* **API Key 快速接入**：通过简单的 Bearer Token 认证，提供 3 个核心工具，适合需要在 5 分钟内完成自助接入的快速原型验证、内部工具开发及功能测试。
* **OAuth 2.0 完整接入**：采用授权码模式，提供完整的 7 个工具链，支持 Agent 内支付闭环及订单全生命周期管理，适合企业级生产应用。

具体选型可根据**项目阶段、支付需求、用户体验及团队开发资源**综合评估。

***

# 一、MCP 协议与 RollingGo MCP 服务概述

## 1.1 什么是 MCP

MCP（Model Context Protocol）是连接 AI 模型与外部数据源、工具及业务系统的标准化协议。

传统 AI 集成通常采用点对点方式：

> N 个 AI 应用 × M 个业务系统 = N × M 套集成关系

MCP 通过统一的 **JSON-RPC 2.0** 协议进行标准化连接，将复杂度从 **N × M 降低至 N + M**，实现：

* 一次接入
* 标准化调用
* 多模型通用
* 统一权限管理
* 统一工具发现

## 1.2 什么是 RollingGo MCP

RollingGo MCP 是基于 MCP 协议封装的**酒店预订领域专用服务**，为 AI Agent 和智能应用提供标准化的：

* 酒店搜索
* 酒店详情查询
* 价格确认
* 酒店预订
* 在线支付
* 订单查询
* 订单详情管理

RollingGo MCP 将复杂的酒店供应商 API 抽象为统一的 MCP Tool 接口，开发者无需深入理解不同酒店供应商的异构 API，即可快速构建具备酒店预订能力的 AI 应用。

## 1.3 技术架构

MCP 采用 Client-Server 双层架构。

在 RollingGo MCP 场景中：

**MCP Server**

负责统一封装：

* 酒店业务能力
* Tools
* Resources
* Prompts
* 权限控制
* 日志及审计

**MCP Client**

集成在 AI Agent 或应用侧，通过标准 MCP 协议发现并调用 Server 提供的能力。

这种架构实现了服务端能力与客户端应用的解耦。当工具、权限或业务逻辑发生变化时，可以集中在 Server 端进行维护，而 Client 只需遵循标准协议即可使用。

***

# 二、两种接入方式核心对比

RollingGo MCP 提供两种技术路径，核心差异集中在**认证方式、工具能力、支付体验和接入复杂度**。

| 对比项 | API Key 快速接入 | OAuth 2.0 完整接入 |
| - | - | - |
| Service | RollingGo MCP | RollingGo MCP |
| Authentication | Bearer Token | OAuth 2.0 授权码模式 |
| 接入方式 | 静态 API Key | 用户授权 + Access Token |
| Available Tools | 3 个 | 7 个 |
| 酒店搜索 | ✅ | ✅ |
| 酒店详情 | ✅ | ✅ |
| 搜索标签 | ✅ | ✅ |
| 价格确认 | ❌ | ✅ |
| 酒店预订 | 基础支持 | ✅ |
| Agent 内支付 | ❌ | ✅ |
| 订单查询 | ❌ | ✅ |
| 订单详情 | ❌ | ✅ |
| 用户级身份 | ❌ | ✅ |
| 订单生命周期管理 | ❌ | ✅ |
| 接入复杂度 | 低 | 较高 |
| 接入速度 | 约 5 分钟 | 通常 3–5 天开发 |
| 商务流程 | 无 | 企业级对接 |
| 适合阶段 | MVP / 原型 / 测试 | 生产 / 企业级应用 |

### 2.1 API Key 工具

API Key 模式提供 3 个核心工具：

```text theme={null}
searchHotels
getHotelDetail
getHotelSearchTags
```

认证方式：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

### 2.2 OAuth 2.0 工具

OAuth 2.0 模式提供完整的 7 个工具链：

```text theme={null}
getHotelSearchTags
searchHotels
getHotelDetail
hotelPriceConfirm
createHotelBookingWithPaymentURL
searchHotelOrders
getHotelOrderDetail
```

***

# 三、API Key 快速接入

## 3.1 核心优势

### 接入速度快

开发者完成申请后即可获取 API Key，通过简单的 HTTP Header 配置即可开始调用。

整个过程可以在 **5 分钟左右完成基础接入**。

### 技术门槛低

只需要在请求头中加入：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

无需实现复杂的 OAuth 授权流程。

### 完全自助

开发者可以自行申请和配置，无需复杂商务对接。

### 适合快速验证

特别适合：

* MVP
* 功能验证
* 内部工具
* 技术预研
* 快速原型

***

# 四、API Key 的适用场景与局限

## 4.1 适用场景

### 内部工具

例如：

* 企业差旅查询系统
* 内部酒店查询工具
* 酒店信息分析工具

### 功能验证

用于快速验证：

* 酒店搜索
* 酒店库存
* 酒店详情
* 搜索结果准确性

### 已有支付体系的平台

对于已经具备成熟支付和订单系统的 OTA、旅游平台，可以将 RollingGo MCP 作为酒店库存补充渠道。

***

## 4.2 功能局限

### 支付体验割裂

API Key 模式下，用户预订后需要跳转到 RollingGo H5 页面完成支付。

用户会：

> Agent → RollingGo H5 → 支付

这一过程会中断 Agent 内的对话流程。

### 订单能力有限

API Key 模式不提供：

* 历史订单查询
* 订单详情
* 用户订单状态管理

因此订单售后需要依赖开发者自己的系统或外部流程。

### 权限控制粒度较粗

API Key 本质上是应用级凭证，无法天然实现用户级权限控制。

### 密钥安全需要自行管理

建议：

* 使用环境变量保存 API Key
* 避免将 Key 写入前端代码
* 生产环境配置 IP 白名单
* 根据业务情况增加调用频率限制

***

# 五、OAuth 2.0 完整接入

## 5.1 核心能力

OAuth 2.0 模式采用**授权码模式（Authorization Code）**。

完整流程为：

```text theme={null}
用户
 ↓
开发者 Agent / 应用
 ↓
RollingGo Authorization Server
 ↓
用户授权
 ↓
Authorization Code
 ↓
Client 换取 Access Token
 ↓
调用 RollingGo MCP
```

Access Token 用于后续 MCP Tool 调用。

***

# 六、OAuth 2.0 的安全与技术优势

相比 API Key 的静态认证方式，OAuth 2.0 更适合企业级生产环境。

## 6.1 短期访问令牌

Access Token 具备有效期，可以降低长期凭证泄露风险。

## 6.2 Refresh Token

支持在 Access Token 到期后进行刷新，减少用户重复授权。

## 6.3 用户级权限控制

可以基于用户身份和授权范围控制访问权限，更符合最小权限原则。

## 6.4 用户身份上下文

请求能够关联用户身份，从而支持：

* 用户订单管理
* 用户权限控制
* 用户行为分析
* 审计追踪
* 个性化服务

***

# 七、OAuth 2.0 完整工具链

OAuth 2.0 提供完整的 7 个工具，覆盖从酒店搜索到订单管理的完整链路。

## 7.1 搜索与查询

```text theme={null}
getHotelSearchTags
searchHotels
getHotelDetail
```

## 7.2 价格确认

```text theme={null}
hotelPriceConfirm
```

实时确认酒店价格及库存，降低预订过程中出现价格变化的风险。

## 7.3 酒店预订与支付

```text theme={null}
createHotelBookingWithPaymentURL
```

生成支付页面，使用户能够在 Agent 环境内完成预订支付流程。

## 7.4 订单管理

```text theme={null}
searchHotelOrders
getHotelOrderDetail
```

支持：

* 历史订单查询
* 订单详情查询
* 订单状态跟踪
* 售后处理

***

# 八、OAuth 2.0 的核心业务价值

## 8.1 用户体验闭环：不跳出 Agent

API Key 模式：

```text theme={null}
搜索 → 预订 → 跳转 RollingGo H5 → 支付
```

OAuth 2.0 模式：

```text theme={null}
搜索 → 比价 → 下单 → 支付 → 查订单
```

整个流程均可以在开发者自己的 Agent / 应用环境中完成。

用户无需离开当前对话界面，体验更加连贯。

***

# 九、数据归属：手机号与用户关系

在 OAuth 2.0 授权码模式下，用户授权后，相关身份信息可以回流到开发者自己的系统。

这意味着开发者能够进一步建立：

* 用户档案
* 用户订单历史
* 复购体系
* 个性化推荐
* 会员体系
* 用户运营体系

用户关系也更多地沉淀在开发者自身平台。

而 API Key 模式下，用户最终在 RollingGo H5 完成交易，用户数据和订单关系主要沉淀在 RollingGo 侧，开发者更多承担流量入口的角色。

***

# 十、品牌一致性

OAuth 2.0 模式下，用户可以始终在开发者自己的 Agent / 应用环境中完成操作。

用户不会因为支付或订单操作而跳转到 RollingGo 品牌页面。

因此，对于希望：

* 打造自有品牌
* 建立独立用户体验
* 构建完整业务闭环
* 将酒店预订作为核心业务能力

的企业来说，OAuth 2.0 更适合作为长期技术方案。

***

# 十一、功能完整性

OAuth 2.0 提供完整的 7 个工具链：

```text theme={null}
搜索
 ↓
酒店详情
 ↓
价格确认
 ↓
预订
 ↓
支付
 ↓
订单查询
 ↓
订单详情
```

能够支持：

* 实时订单查询
* 订单状态跟踪
* 售后及退改处理
* 用户订单管理
* 全生命周期管理

这使酒店预订能力能够真正嵌入开发者自己的业务系统，而不仅仅是一个外部查询或跳转能力。

***

# 十二、两种模式的优势总结

## API Key 快速接入

**核心定位：快速接入、快速验证、流量导入**

主要优势：

* 5 分钟快速接入
* 技术门槛低
* 无复杂商务流程
* 完全自助
* 适合 MVP 和内部工具
* 适合已有支付体系的平台

适合：

> **先接起来，再验证业务。**

***

## OAuth 2.0 完整接入

**核心定位：深度集成、用户自有、体验闭环**

主要优势：

* 7 个完整工具
* 支持价格确认
* 支持 Agent 内支付
* 支持订单查询
* 支持订单详情
* 支持用户级权限
* 支持完整订单生命周期
* 更适合企业级生产应用

适合：

> **把酒店预订真正做成自己产品的一部分。**

***

# 十三、选型决策指南

建议从三个维度进行选择：

## 13.1 项目阶段

| 项目阶段 | 推荐方案 |
| - | - |
| 概念验证 | API Key |
| MVP | API Key |
| 功能测试 | API Key |
| 产品化 | OAuth 2.0 |
| 规模化生产 | OAuth 2.0 |
| 企业级应用 | OAuth 2.0 |

## 13.2 支付需求

| 支付需求 | 推荐方案 |
| - | - |
| 已有自己的支付体系 | API Key |
| 仅需要酒店查询 | API Key |
| 需要 Agent 内支付 | OAuth 2.0 |
| 需要完整订单闭环 | OAuth 2.0 |

## 13.3 团队资源

| 团队情况 | 推荐方案 |
| - | - |
| 技术资源有限 | API Key |
| 希望快速上线 | API Key |
| 有成熟研发团队 | OAuth 2.0 |
| 有企业级安全能力 | OAuth 2.0 |

***

# 十四、场景化选型建议

## 推荐 API Key

适合：

* 内部酒店查询工具
* 企业差旅系统
* 功能验证测试
* 技术可行性研究
* MVP 产品
* 已有支付系统的大型 OTA
* 酒店库存补充渠道

## 推荐 OAuth 2.0

适合：

* 旅游预订 App
* 酒店比价平台
* 智能旅行助手
* C 端消费应用
* 企业差旅管理平台
* 电商酒店频道
* 会员权益兑换平台
* 高端酒店品牌直销渠道

***

# 十五、实施路径

## 15.1 API Key 实施路径

```text theme={null}
1. 申请 API Key
       ↓
2. 配置 Authorization Header
       ↓
3. 调用 searchHotels
       ↓
4. 验证 MCP 连通性
       ↓
5. 集成其他工具
       ↓
6. 完成功能测试
```

## 15.2 OAuth 2.0 实施路径

```text theme={null}
1. 获取企业级接入文档
       ↓
2. 配置 Client ID / Secret
       ↓
3. 配置 OAuth Callback
       ↓
4. 实现授权码流程
       ↓
5. 实现 Token 管理
       ↓
6. 集成 7 个 MCP Tools
       ↓
7. 完成预订 + 支付全流程测试
```

***

# 十六、关键风险提示

## API Key

主要风险：

* 支付跳转导致用户流失
* 无法直接管理用户订单
* API Key 泄露风险
* 用户级权限能力有限

建议重点优化：

* H5 跳转体验
* Key 安全管理
* IP 白名单
* 调用频率限制

## OAuth 2.0

主要风险：

* 初始集成复杂度较高
* 需要实现 OAuth 授权流程
* 需要维护 Token 生命周期
* 企业级应用通常需要安全及合规评估

***

# 十七、最终选型原则

可以用一句话概括：

> **快速原型用 API Key，生产级应用用 OAuth 2.0。**

更具体地说：

**API Key = 快速接入 + 低门槛 + 快速验证**

适合作为酒店能力的快速接入方案。

**OAuth 2.0 = 深度集成 + 用户自有 + 支付闭环 + 订单管理**

适合作为企业级酒店预订能力的长期架构方案。

对于混合场景，可以采用分阶段策略：

```text theme={null}
阶段一
API Key
快速验证市场和酒店能力

        ↓

阶段二
产品成熟

        ↓

阶段三
OAuth 2.0
完成深度集成、支付闭环和订单管理
```

最终可以理解为：

> **API Key 是“快速接入、流量导入”的轻量方案；OAuth 2.0 是“深度集成、用户自有、体验闭环”的企业级方案。**

如果开发者只是希望快速接入酒店搜索能力，API Key 已经足够；如果希望将酒店预订作为自己产品的核心能力，并实现**搜索、比价、下单、支付、订单管理全流程不离开 Agent**，则应选择 **OAuth 2.0 授权码模式**。


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