麦当劳MCP开发者接入指南：OAuth2.0与API签名实战-代码聚汇网

麦当劳MCP开发者接入指南：OAuth2.0与API签名实战

沂樾

1. 开发者工具接入麦当劳MCP全流程解析

最近在开发者社区看到不少同行在讨论如何将自家应用与麦当劳MCP系统对接，正好上个月我刚完成一个类似项目。今天就把整个接入流程拆解成可实操的步骤，分享几个关键环节的避坑经验。

MCP（McDonald's Commerce Platform）是麦当劳面向开发者提供的统一商业接口平台，通过标准化API实现订单管理、门店查询、优惠券核销等核心功能。接入后你的应用就能直接调用麦当劳的线上服务能力，比如实现"一键下单麦乐送"这类功能。整个过程主要涉及开发者账号申请、接口权限配置、认证鉴权和业务接口调用四个阶段，最关键的环节是正确处理OAuth2.0认证流程和请求签名。

重要提示：正式接入前建议先在沙箱环境测试，麦当劳为开发者提供了完整的模拟环境，避免直接操作生产数据导致异常订单。

1.1 前期准备工作清单

开始编码前需要准备好这些基础材料：

企业资质文件：营业执照扫描件（个人开发者可用身份证）
服务器信息：准备HTTPS域名（必须备案）和固定IP地址
开发环境：Postman或类似API调试工具，推荐使用Insomnia更直观
技术储备：熟悉OAuth2.0协议和JWT规范，了解基本的HTTP签名机制

在麦当劳开发者门户（developer.mcdonalds.com）注册账号时，会遇到账户类型选择。如果只是测试接口功能，选择"个人开发者"即可；若要上线真实服务，必须用企业资质注册。我遇到过有团队用个人账号开发完才发现无法迁移到企业账号，导致所有配置要重做的情况。

2. 认证鉴权核心流程详解

2.1 获取API访问凭证

接入MCP的第一步是获取合法的访问令牌（access_token），这个流程涉及三个关键接口：

获取授权码（OAuth2.0 authorization code）

bash复制GET https://auth.mcdonalds.com/oauth2/authorize?
  response_type=code&
  client_id=你的应用ID&
  redirect_uri=回调地址&
  scope=order_api%20store_api

兑换访问令牌（关键步骤）

bash复制POST https://auth.mcdonalds.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=上一步获取的授权码&
redirect_uri=与上一步一致的回调地址&
client_id=你的应用ID&
client_secret=你的应用密钥

刷新令牌（access_token过期时使用）

bash复制POST https://auth.mcdonalds.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=之前返回的refresh_token&
client_id=你的应用ID&
client_secret=你的应用密钥

踩坑记录：client_secret在测试环境和生产环境是不同的，有次我在生产环境误用了测试环境的密钥，导致持续返回403错误，排查了2小时才发现问题。

2.2 请求签名机制

MCP要求所有业务接口请求都必须携带数字签名（X-Mc-Signature），签名算法如下：

拼接签名字符串：
- HTTP方法（大写）
- 请求路径（如"/v1/orders"）
- 查询字符串（按参数名排序后URL编码）
- 当前时间戳（Unix秒级）
- 请求体原始JSON（保留原始空格和换行）
使用HMAC-SHA256算法计算签名：

python复制import hmac
import hashlib

signature = hmac.new(
    client_secret.encode(),
    msg=sign_string.encode(),
    digestmod=hashlib.sha256
).hexdigest()

在请求头中添加：
- X-Mc-Timestamp: 生成签名时使用的时间戳
- X-Mc-Signature: 计算得到的签名值

3. 核心业务接口调用示例

3.1 门店信息查询

获取周边麦当劳门店是最常用的功能，这个接口不需要特殊权限：

bash复制GET https://api.mcdonalds.com/v1/stores?
  latitude=39.9042&
  longitude=116.4074&
  radius=5000&
  limit=10
Headers:
  Authorization: Bearer <access_token>
  X-Mc-Timestamp: 1625097600
  X-Mc-Signature: 计算得到的签名

返回的JSON数据结构示例：

json复制{
  "stores": [
    {
      "storeId": "10086",
      "name": "王府井餐厅",
      "address": "北京市东城区王府井大街88号",
      "latitude": 39.9087,
      "longitude": 116.4094,
      "services": ["McDelivery", "24H"],
      "openStatus": "OPEN"
    }
  ]
}

3.2 创建订单接口

下单接口需要order_api权限，请求体需要注意几个特殊字段：

json复制{
  "storeId": "10086",
  "items": [
    {
      "productCode": "2101",
      "quantity": 1,
      "modifiers": [
        {"code": "NO_ICE"}
      ]
    }
  ],
  "payment": {
    "method": "WECHAT_PAY",
    "amount": 38.5
  },
  "deliveryInfo": {
    "address": "北京市朝阳区建国路93号",
    "contactPhone": "13800138000"
  }
}

常见错误处理：

400错误：检查productCode是否有效（需提前调用商品目录接口）
403错误：确认access_token未过期且具有order_api权限
429错误：触发了接口限流，需要添加请求重试机制

4. 实战中的经验技巧

4.1 令牌管理最佳实践

access_token有效期通常为2小时，refresh_token有效期14天。建议这样设计令牌管理：

内存缓存access_token并设置自动刷新
持久化存储refresh_token
实现令牌自动续期机制：

python复制def get_valid_token():
    if cache.has('access_token'):
        return cache.get('access_token')
    
    refresh_token = db.get_refresh_token()
    new_token = refresh_access_token(refresh_token)
    cache.set('access_token', new_token, ttl=7200-300) # 提前5分钟过期
    return new_token

4.2 调试技巧

当接口返回异常时，按这个顺序排查：

检查X-Mc-Timestamp与服务端时间差（允许±5分钟）
用签名工具重新生成签名对比
捕获原始请求和响应（建议使用Charles抓包）
检查OAuth作用域是否包含所需权限

我习惯在项目里内置一个签名验证工具，开发时能实时对比自己生成的签名与服务端期望的是否一致：

javascript复制// 签名验证工具示例
function verifySignature(request, secret) {
  const signString = buildSignString(request);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signString)
    .digest('hex');
  return expected === request.headers['x-mc-signature'];
}

4.3 性能优化建议

门店查询接口启用gzip压缩后，响应体积可减少70%
对商品目录等不常变的数据做本地缓存（注意麦当劳要求的缓存时效）
批量接口支持最多50个ID同时查询，减少网络请求次数

接入过程中如果遇到400错误提示"the supported API model names are..."，这通常意味着请求头或参数格式不正确。建议先用Postman测试基础请求，再移植到代码中。有次我在Unity项目中遇到这个报错，最后发现是HTTP客户端自动添加了不兼容的Header导致。

对于移动端开发者，特别注意Android 9+的HTTPS限制。需要配置network_security_config.xml允许麦当劳的证书链：

xml复制<network-security-config>
  <domain-config cleartextTrafficPermitted="false">
    <domain includeSubdomains="true">api.mcdonalds.com</domain>
    <trust-anchors>
      <certificates src="system"/>
      <certificates src="@raw/mcdonalds_ca"/>
    </trust-anchors>
  </domain-config>
</network-security-config>

整个接入过程最耗时的部分是签名机制的调试，建议先单独验证签名逻辑正确性。麦当劳提供了签名验证工具，可以在开发者门户的"API Tools"中找到。遇到403 country forbidden错误时，检查请求IP是否在国内（麦当劳API目前仅限中国大陆地区访问）。