MCP OAuth 授权接入指南

途牛开放平台的远程 MCP 服务使用 OAuth 2.1 授权。客户端连接 MCP 服务时，会先跳转到途牛开放平台完成登录和授权确认，授权成功后客户端会自动携带访问令牌调用 MCP 工具。

当前推荐优先使用支持 OAuth 的 MCP 客户端，例如 Cursor、MCPJam Inspector 等。

可用服务

生产环境统一使用 HTTPS 和 Streamable HTTP。

服务	MCP Server URL	说明
订单服务	`https://openapi.tuniu.cn/hybrid/mcp/order`	查询用户订单等订单相关能力
酒店服务	`https://openapi.tuniu.cn/hybrid/mcp/hotel`	酒店查询、详情、预订相关能力
国内机票服务	`https://openapi.tuniu.cn/hybrid/mcp/flight`	机票查询、预订相关能力
火车票服务	`https://openapi.tuniu.cn/hybrid/mcp/train`	火车票查询、预订相关能力
景点门票服务	`https://openapi.tuniu.cn/hybrid/mcp/ticket`	景点门票查询、预订相关能力

开放平台控制台：

text

https://open.tuniu.com/mcp

旧版 API Key MCP 服务可能仍使用 /mcp/... 路径。OAuth 授权 MCP 服务统一使用 /hybrid/mcp/... 路径。

接入方式选择

方式	适用场景	客户需要做什么
DCR 动态注册	客户端支持 MCP OAuth 动态注册，例如 Cursor	只填写 MCP Server URL，浏览器完成登录授权
CIMD 客户端元数据	客户端支持使用公开 metadata URL 作为 client_id	提供 HTTPS metadata URL，浏览器完成登录授权
预注册授权应用	企业系统、合作方应用、固定客户端，或客户端不支持 DCR/CIMD	联系途牛申请 client_id / client_secret 后配置

大多数用户优先选择 DCR 动态注册。如果客户端不支持 DCR，再考虑 CIMD 或预注册授权应用。

方式一：DCR 动态注册

DCR 是 Dynamic Client Registration。支持 DCR 的 MCP 客户端可以自动向途牛开放平台注册 OAuth 客户端。

如何使用

在客户端中新增 MCP Server，填写对应服务地址即可。

Cursor 示例：

json

{
  "mcpServers": {
    "tuniu-order": {
      "type": "streamableHttp",
      "url": "https://openapi.tuniu.cn/hybrid/mcp/order"
    },
    "tuniu-hotel": {
      "type": "streamableHttp",
      "url": "https://openapi.tuniu.cn/hybrid/mcp/hotel"
    },
    "tuniu-flight": {
      "type": "streamableHttp",
      "url": "https://openapi.tuniu.cn/hybrid/mcp/flight"
    }
  }
}

保存后客户端会自动打开浏览器，用户完成以下操作：

text

1. 登录途牛开放平台账号
2. 确认客户端申请的授权范围
3. 返回 MCP 客户端继续使用工具

客户端会自动保存访问令牌，用户不需要手动复制 Token。

方式二：CIMD 客户端元数据

CIMD 是 Client ID Metadata Document。支持 CIMD 的客户端会把 client_id 设置为一个公开的 metadata URL。途牛开放平台会读取该 metadata，校验客户端名称、回调地址和授权范围。

客户端 metadata 示例

json

{
  "client_id": "https://client.example.com/.well-known/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://client.example.com",
  "redirect_uris": [
    "http://127.0.0.1:12346/oauth/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "capability:invoke",
  "token_endpoint_auth_method": "none"
}

如何使用

在支持 CIMD 的客户端中填写：

text

MCP Server URL: 选择上方服务地址
Registration: CIMD / URL-based
Client Metadata URL: 客户端公开的 metadata URL
Scope: capability:invoke

生产环境要求 metadata URL 使用 HTTPS。

方式三：预注册授权应用

预注册授权应用适合企业系统、合作方应用、固定客户端，或无法使用 DCR/CIMD 的客户端。

申请预注册

接入方向途牛提供：

应用名称、负责人和联系方式；
测试及生产环境的 HTTPS redirect_uri；
需要使用的 MCP 能力；
申请的 Scope。仅调用 MCP 时申请 capability:invoke；需要识别并关联途牛用户时，同时申请 openid profile user:basic；如需长期登录，再申请 offline_access。

途牛审核后提供：

text

client_id
client_secret（服务端应用）
允许的 Redirect URI
允许的 Scope

申请联系方式：

text

电话：1801396339
邮箱：majing5@tuniu.com

凭证安全

client_secret 只能保存在服务端，不能写入浏览器、小程序、App 安装包、日志或公开代码仓库。

OAuth 与资源元数据地址

用途	地址
配置发现	`https://openapi.tuniu.cn/.well-known/openid-configuration`
用户授权	`https://openapi.tuniu.cn/oauth2/auth`
获取 Token	`https://openapi.tuniu.cn/oauth2/token`
用户信息	`https://openapi.tuniu.cn/userinfo`
撤销 Token	`https://openapi.tuniu.cn/oauth2/revoke`

资源元数据地址由固定前缀与 MCP 路径组成：

text

https://openapi.tuniu.cn/.well-known/oauth-protected-resource<路由路径>

例如酒店服务对应：

text

https://openapi.tuniu.cn/.well-known/oauth-protected-resource/hybrid/mcp/hotel

客户端配置

如果客户端支持手动 OAuth 配置，请填写：

text

MCP Server URL: 选择上方服务地址
Authorization Endpoint: https://openapi.tuniu.cn/oauth2/auth
Token Endpoint: https://openapi.tuniu.cn/oauth2/token
Client ID: 途牛提供的 client_id
Client Secret: 途牛提供的 client_secret（如适用）
Scope: 平台审核通过的 Scope
PKCE: S256
Transport: Streamable HTTP

Authorization Code + PKCE

预注册应用应使用 Authorization Code + PKCE 完成用户授权。每次授权生成随机 state 和 code_verifier，并按 BASE64URL(SHA256(code_verifier)) 计算 code_challenge。

以下是需要建立途牛账户关联的酒店服务示例：

http

GET https://openapi.tuniu.cn/oauth2/auth
  ?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=<URL_ENCODED_REDIRECT_URI>
  &scope=openid%20profile%20user%3Abasic%20capability%3Ainvoke
  &state=<RANDOM_STATE>
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fopenapi.tuniu.cn%2Fhybrid%2Fmcp%2Fhotel

用户登录并同意后，途牛回调：

text

<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>

接入方必须先校验 state，再使用一次性授权码换取 Token。redirect_uri 必须与预注册值完全一致。

服务端应用换取 Token 的示例：

bash

curl -sS -X POST 'https://openapi.tuniu.cn/oauth2/token' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code_verifier=$CODE_VERIFIER"

应用是否提交 client_secret、Token 可访问哪些 MCP 路由，以预注册结果为准。

建立或解除账户关联

申请了 openid profile user:basic 的应用可以调用 UserInfo：

bash

curl -sS 'https://openapi.tuniu.cn/userinfo' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

使用 issuer + sub 建立账户关联，不要仅凭手机号或邮箱自动合并账户。用户解绑时，应停止使用 Token、调用撤销接口，并删除本地账户关联。

授权流程

不论使用 DCR、CIMD 还是预注册授权应用，用户侧看到的流程基本一致：

text

1. MCP 客户端连接途牛 MCP 服务
2. 客户端发现需要 OAuth 授权
3. 浏览器打开途牛开放平台登录/授权页面
4. 用户登录并确认授权
5. 客户端自动获取访问令牌
6. 客户端携带令牌调用 MCP 工具

授权成功后，用户可以在开放平台控制台查看和管理授权记录。

Scope 说明

Scope	用途	是否默认需要
`capability:invoke`	调用 MCP 工具	是
`openid`	获取用户身份标识	仅账户关联场景
`profile`	获取用户基础资料	仅账户关联场景
`user:basic`	访问途牛用户基础信息	仅账户关联场景
`offline_access`	申请长期授权及 Refresh Token	按需申请

默认 MCP 接入只需要 capability:invoke。需要通过 UserInfo 建立账户关联时，使用：

text

openid profile user:basic capability:invoke

Scope 使用空格分隔，不要使用逗号。最终可用范围以平台审核结果为准。

调用 MCP

请求 Header：

http

Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream

如响应包含 Mcp-Session-Id，后续请求应原样带回。

初始化

将以下 JSON 以 POST 方式发送到所选 MCP 地址：

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {"name": "<CLIENT_NAME>", "version": "1.0"}
  }
}

初始化成功后发送 notifications/initialized。

获取并调用工具

获取工具清单：

json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

酒店查询示例：

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tuniuHotelSearch",
    "arguments": {
      "cityName": "南京",
      "checkIn": "2026-09-10",
      "checkOut": "2026-09-11",
      "adultNum": 2,
      "childNum": 0
    }
  }
}

其他服务只需替换 MCP 地址、工具名和参数。工具名称及参数结构以实时 tools/list 返回的 inputSchema 为准。

有效期说明

当前远程 MCP OAuth access token 默认有效期约 7 天。客户端通常会自动使用 refresh token 或重新发起授权，用户无需手动复制 token。

预注册授权应用的 client_secret 创建后只展示一次，目前不自动过期；如果泄露，应联系途牛禁用旧应用并重新创建。

开放平台网页登录态和 OAuth 授权记忆有效期由平台配置控制，当前授权记忆默认约 24 小时。

安全建议

不要把 client_secret、Bearer Token 发给无关人员。
不要把密钥提交到公开仓库。
企业系统接入建议使用预注册授权应用，并由企业后台统一管理。
支持 DCR 的客户端优先使用自动授权流程。
静态 Bearer Token 仅建议作为临时调试或兼容方案。
仅在用户授权范围内调用接口，并安全保存 Token。
涉及下单、取消、退款等操作时，应先展示商品、日期、人员、金额和退改信息，并取得用户本次明确确认。

常见问题

客户端提示资源不匹配

请确认客户端填写的 MCP Server URL 与平台提供的服务地址完全一致。例如订单服务应使用：

text

https://openapi.tuniu.cn/hybrid/mcp/order

客户端提示 invalid_scope

基础 MCP 调用请使用：

text

capability:invoke

账户关联场景请使用平台审核通过的 Scope，并以空格分隔，例如：

text

openid profile user:basic capability:invoke

不要使用逗号分隔，例如：

text

openid,capability:invoke

客户端不支持自动 OAuth

请联系途牛申请预注册授权应用，或使用支持 DCR/CIMD 的 MCP 客户端。

MCP OAuth 授权接入指南 ​

可用服务 ​

接入方式选择 ​

方式一：DCR 动态注册 ​

如何使用 ​

方式二：CIMD 客户端元数据 ​

客户端 metadata 示例 ​

如何使用 ​

方式三：预注册授权应用 ​

申请预注册 ​

OAuth 与资源元数据地址 ​

客户端配置 ​

Authorization Code + PKCE ​

建立或解除账户关联 ​

授权流程 ​

Scope 说明 ​

调用 MCP ​

初始化 ​

获取并调用工具 ​

有效期说明 ​

安全建议 ​

常见问题 ​

客户端提示资源不匹配 ​

客户端提示 invalid_scope ​

客户端不支持自动 OAuth ​

MCP OAuth 授权接入指南

可用服务

接入方式选择

方式一：DCR 动态注册

如何使用

方式二：CIMD 客户端元数据

客户端 metadata 示例

如何使用

方式三：预注册授权应用

申请预注册

OAuth 与资源元数据地址

客户端配置

Authorization Code + PKCE

建立或解除账户关联

授权流程

Scope 说明

调用 MCP

初始化

获取并调用工具

有效期说明

安全建议

常见问题

客户端提示资源不匹配

客户端提示 invalid_scope

客户端不支持自动 OAuth