腾讯出行服务MCP开发文档

目录

1. 创建MCP KEY
2. 快速开始
   • 协议支持
   • 接入地址
   • 接入方式
3. 工具列表
   • 概述
   • 获取输入地点关键词相关的地点推荐详情
   • 获取附近可用车辆
   • 获取打车预估价格和路线规划
   • 获取打车的二维码或者微信短链
4. 部分错误码说明
   • 成功状态码
   • json rpc 2.0 标准错误
   • 系统错误 (500)
   • 调用方错误 (5000-5099)
   • 参数和数据错误 (10001-10050)
   • HTTP 状态码说明

1. 创建MCP KEY

登录腾讯出行服务开放平台控制台，申请MCP KEY。具体参考腾讯出行服务MCP接入指南。

2. 快速开始

协议支持

支持 SSE 协议 和 Streamable HTTP 协议，所有请求均基于 JSON-RPC 2.0 进行通信。

接入地址

SSE协议接入地址：

https://weixin.go.qq.com/mcp/gw-sse/sse

Streamable HTTP协议接入地址：

https://weixin.go.qq.com/mcp/gw-stream-http/mcp

接入方式

请求头鉴权接入，需要在请求头 Authorization 中填入申请的MCP KEY。

以Streamable HTTP协议示例：

curl -X "POST" 'https://weixin.go.qq.com/mcp/gw-stream-http/mcp' \
--header 'Authorization: YOUR_MCP_KEY' \
--header  'Content-Type: application/json' \
--data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
}'

3. 工具列表

3.1 概述

能力	标识	描述
获取输入地点关键词相关的地点推荐详情	get_place_suggestion	用于获取某一个城市的输入地点关键字相关的地点推荐详情，返回信息中含有地点的经纬度、省份、城市以及POI详情等信息
获取附近可用车辆	get_nearby_empty_car	获取附近可用车辆
获取打车预估价格和路线规划	get_takercar_estimate_price_and_route_plan	获取打车预估价格和两地之间的路线规划。其中当两地之间的距离小于200公里时才会有路线规划的信息，当两地的距离大于200公里时没有路线规划的信息
获取打车的二维码或者微信短链	obtain_takecar_qrCode_or_wx_short_url	获取打车的二维码或者微信短链，可以通过该信息跳转到腾讯出行服务小程序打车冒泡页

3.2 获取输入地点关键词相关的地点推荐详情

输入参数结构

参数名称	类型	是否必填	参数描述
seqId	string	是	请求的唯一标识字符串
keyword	string	是	输入地点的关键词
region	string	是	限制城市范围，根据城市名称限制地域范围， 如，仅获取武汉市范围内的提示内容，则输入武汉市
pageIndex	integer	是	分页查询需要，代表分页页码。从1开始，最大页码需通过返回值中的count进行计算，必须与请求中的pageSize同时使用。一般填入1
pageSize	integer	是	分页查询需要，代表分页时每页条数，取值范围1-20，必须与请求参数中的pageIndex同时使用。一般填入20
policy	integer	否	检索策略，非必填。如果不填写，默认是0（常规策略）。如果需要填写，只能填写0或者1或者10或者11，具体说明：policy=0：默认，常规策略；policy=1：本策略主要用于收货地址、上门服务地址的填写，提高了小区类、商务楼宇、大学等分类的排序，过滤行政区、道路等分类（如海淀大街、朝阳区等），排序策略引入真实用户对输入提示的点击热度，使之更为符合此类应用场景，体验更为舒适；policy=10：出行场景（网约车） – 起点查询；policy=11：出行场景（网约车） – 终点查询
region_fix	integer	否	地区修正标识，非必填。如果不填写，默认是0（不限制当前城市）。如果需要填写，只能填写0或者1，0代表不限制当前城市，会召回其他城市的poi，1代表仅限制在当前城市
location	string	否	定位坐标，非必填。若传入，当搜索关键词为类别词（如酒店、餐馆时），与此坐标距离近的地点将靠前显示，格式：location=lat,lng。示例location=39.11457,116.55332

返回参数结构

参数名称	类型	参数描述
code	integer	响应状态码，0表示成功
message	string	响应消息
data	object	响应数据对象，详见ResponseData结构定义

ResponseData结构定义

参数名称	类型	参数描述
count	integer	搜索结果总数
dataList	List	地点数据列表，详见PlaceData结构定义
message	string	状态说明
requestId	string	请求ID
status	integer	状态码，0为正常，其它为异常

PlaceData结构定义

参数名称	类型	参数描述
id	string	POI地点唯一标识（返回值字段中type为4时不返回）
title	string	地点名称
address	string	详细地址（返回值字段中type为4时不返回）
category	string	地点分类（返回值字段中type为4时不返回）
type	integer	POI类型，值说明：0:普通POI / 1:公交车站 / 2:地铁站 / 3:公交线路 / 4:行政区划
location	object	位置坐标信息，详见Location结构定义
province	string	省份名称（返回值字段中type为4时不返回）
city	string	城市名称（返回值字段中type为4时不返回）
district	string	区县名称（返回值字段中type为4时不返回），当返回值字段中type（POI类型）为3（公交线路）时，district由city补全
adcode	integer	行政区划代码
subPois	List	子POI列表，详见SubPoi结构定义

SubPoi结构定义

参数名称	类型	参数描述
parent_id	string	主地点ID，对应PlaceData中的地点ID
id	string	地点唯一标识
title	string	地点名称
address	string	地址
category	string	POI（地点）分类
location	object	坐标，详见Location结构定义
adcode	number	行政区划代码
city	string	地点所在城市名称

Location结构定义

参数名称	类型	参数描述
lat	number	纬度坐标
lng	number	经度坐标

3.3 获取附近可用车辆

输入参数结构

参数名称	类型	是否必填	参数描述
seqId	string	是	请求的唯一标识字符串
cityCode	string	是	当前经纬度所在城市的国家6位行政区划代码
latitude	number	是	所在纬度
longitude	number	是	所在经度
radius	integer	是	附近半径范围，单位米。示例，传入2000，代表获取附近2000米的范围内的可用车辆

返回参数结构

参数名称	类型	参数描述
code	integer	响应状态码，0表示成功
message	string	响应消息
data	object	响应数据对象，详见ResponseData结构定义

ResponseData结构定义

参数名称	类型	参数描述
nearbyCarList	List	运力空车列表，详见SupplierNearbyCarVo结构定义
hasMoreSupplier	boolean	是否有更多运力商
nextSupplierCursor	integer	运力商翻页游标
count	integer	点位总数量

SupplierNearbyCarVo结构定义

参数名称	类型	参数描述
supplierId	string	运力ID
emptyCarList	List	空车列表，详见NearbyCarVo结构定义

NearbyCarVo结构定义

参数名称	类型	参数描述
longitude	number	经度
latitude	number	纬度
direction	number	车头朝向角，顺时针方向，正北为0度
distance	integer	距离，单位：米
duration	integer	预计到达时间，单位：秒
updateTime	integer	更新时间
carColor	string	车辆颜色

3.4 获取打车预估价格和路线规划

输入参数结构

参数名称	类型	是否必填	参数描述
seq_id	string	是	请求的唯一标识字符串
cityCode	string	是	出发点经纬度所在城市的国家6位行政区划代码
fromAddress	string	是	出发点地址
fromLat	number	是	出发点纬度
fromLng	number	是	出发点经度
toAddress	string	是	目的地地址
toLat	number	是	目的地纬度
toLng	number	是	目的地经度
departureTime	integer	是	毫秒级时间戳，orderServiceType=1(实时单)下填入当时时间毫秒级时间戳，orderServiceType=2(预约单)下填入出发时间的毫秒级时间戳
currentLat	number	否	当前位置纬度
currentLng	number	否	当前位置经度
carTypeRange	integer	否	计算预估价格信息时使用车型范围，非必填。如果不填写，默认是1(只计算默勾车型价格）。如果需要填写，只能填写1或者2。1代表只计算默勾车型价格 ；2代表计算全部车型价格。
orderServiceType	integer	否	订单类型，非必填。如果不填写，默认是1(实时单）。如果需要填写，只能填写1或者2。1代表实时单；2代表预约单。

返回参数结构

参数名称	类型	参数描述
code	integer	响应状态码，0表示成功
message	string	响应消息
data	object	响应数据对象，详见ResponseData结构定义

ResponseData结构定义

参数名称	类型	参数描述
lowestPrice	integer	打车最低价（不含拼车），单位：分
highestPrice	integer	打车最高价（不含拼车），单位：分
distance	integer	预估里程，单位：米
estimateTime	integer	预估时长，单位：秒
pickupTime	integer	预估接单时长，单位：秒
downgrade	boolean	是否为降级结果
checkedMaxDiscount	integer	勾选车型最大优惠金额，单位：分，默认值：0
spCount	integer	运力商数量，默认值：0
estimatedProducts	List	车型预估列表，详见EstimatedProduct结构定义
polyline	string	路线规划时有返回航线点坐标，格式：经度1,纬度1;经度2,纬度2

EstimatedProduct结构定义

参数名称	类型	参数描述
rideType	integer	运力类型
estimatedPrices	List	运力商预估列表，详见EstimatedPrice结构定义

EstimatedPrice结构定义

参数名称	类型	参数描述
name	string	运力商车型名称，示例：滴滴快车、滴滴特惠
spId	integer	运力商编码
estimatePrice	integer	预估价格，单位：分
originEstimatePrice	integer	运力商原始预估价，单位：分
discountAmount	integer	优惠金额，单位：分，默认值：0
defaultChecked	integer	是否默认勾选，1-是，0-否，默认值：0
carpoolEstimatedPrice	CarpoolEstimatedPrice	拼车询价信息，详见CarpoolEstimatedPrice结构定义

CarpoolEstimatedPrice结构定义

参数名称	类型	参数描述
waitReward	WaitReward	等待优惠，详见WaitReward结构定义
waitMustGoInfo	WaitMustGoInfo	等必走信息，详见WaitMustGoInfo结构定义
prices	List	拼车价格，详见CarpoolPrice结构定义

WaitReward结构定义

参数名称	类型	参数描述
waitTime	integer	等待时间，单位：秒
amount	integer	立减金金额，单位：分

WaitMustGoInfo结构定义

参数名称	类型	参数描述
hit	boolean	是否命中等必走，默认值：false
waitTime	integer	等待时间，单位：秒

CarpoolPrice结构定义

参数名称	类型	参数描述
seatNum	integer	需要的座位数
priceInfos	List	拼车价格信息，详见CarpoolPriceInfo结构定义

CarpoolPriceInfo结构定义

参数名称	类型	参数描述
poolNum	integer	拼友数量，仅特价拼车有效，默认值：0
carpoolSuccess	boolean	是否拼车成功，默认值：false
estimatePrice	integer	预估价，单位：分

3.5 获取打车的二维码或者微信短链

输入参数结构

参数名称	类型	是否必填	参数描述
seqId	string	是	请求的唯一标识字符串
start	object	否	起始点位置信息，不填写时默认以当前位置作为起始点，详见Placelnfo结构定义
end	object	是	目的地位置信息，详见PlaceInfo结构定义
type	integer	是	生成类别链接规则类型，只能填写1或者2，1代表生成二维码，取返回值的imageUrl字段；2代表生成短链，取返回值的shortUrl字段

PlaceInfo结构定义

参数名称	类型	是否必填	参数描述
title	string	是	地点名称
latitude	number	是	纬度坐标
longitude	number	是	经度坐标
cityCode	string	是	经纬度所在城市的国家6位行政区划代码
address	string	否	详细地址
cityName	string	否	所在城市名称
province	string	否	所在省份名称

返回参数结构

参数名称	类型	参数描述
code	integer	响应状态码，0表示成功
message	string	响应消息
data	object	响应数据对象，详见ResponseData结构定义

ResponseData结构定义

字段名称	类型	说明
shortUrl	string	短链url
imageUrl	string	二维码图片url

4. 部分错误码说明

成功状态码

错误码	说明
0	请求成功

json rpc 2.0 标准错误

错误码	说明
-32700	ErrCodeParse
-32600	ErrCodeInvalidRequest
-32601	ErrCodeMethodNotFound
-32602	ErrCodeInvalidParams
-32603	ErrCodeInternal

系统错误 (500)

错误码	说明	解决方案
500	服务器内部错误	请稍后重试，如持续出现请联系技术支持

调用方错误 (5000-5099)

错误码	说明	解决方案
5000	未知的调用方返回结果	请检查请求参数和调用方式是否正确
5001	调用方上下文未初始化	请确保已正确配置调用方信息
5002	内部错误	请稍后重试，如持续出现请联系技术支持

参数和数据错误 (10001-10050)

错误码	说明	解决方案
10001	数据库错误	请稍后重试，如持续出现请联系技术支持
10002	错误的值类型	请检查请求参数的数据类型是否正确
10003	参数错误	请检查必填参数是否完整，参数格式是否正确
10004	请求过于频繁	请降低请求频率，稍后重试
10005	解密失败	请检查加密参数是否正确
10006	用户不存在	请检查用户 ID 是否正确
10007	用户已注销	该用户已注销，无法继续操作
10008	存在未完成订单	请先完成或取消未完成的订单

HTTP 状态码说明

除了业务错误码外，MCP Server还会返回标准的 HTTP 状态码：

HTTP 状态码	说明
200	请求成功（具体业务是否成功需查看响应中的 code 字段）
400	请求参数错误
401	未授权，请检查认证信息
403	禁止访问，权限不足
404	请求的资源不存在
429	请求过于频繁，触发限流
500	服务器内部错误
502	网关错误
503	服务暂时不可用
504	网关超时