核心用法
Shippo MCP 技能是官方提供的托管式物流接口，通过 https://mcp.shippo.com 暴露 4 个元工具（shippo_list_tools、shippo_describe_tool、shippo_read_execute_tool、shippo_write_execute_tool）来间接调用底层 30+ 承运商（USPS、UPS、FedEx、DHL 等）的完整 API。用户首次使用时通过 Shippo OAuth 一键授权，无需本地配置或存储密钥。
典型工作流：
1. 地址验证：CreateAddress → ValidateAddress，检查 validation_result（valid/invalid/partially_valid），注意 residential/commercial 分类影响附加费
2. 运费比价：CreateShipment 提交收发地址和包裹尺寸（必须为字符串如 "10"），返回 rates 数组，按 carrier、价格、时效筛选
3. 标签购买：用户选定 rate 后，必须显式确认 carrier、service、cost、ETA，再调用 CreateTransaction，返回 label_url（完整 S3 签名 URL，不可截断）和 tracking number
4. 国际发货：需先创建 CustomsItem 和 CustomsDeclaration，选择正确的 contents_type（MERCHANDISE/GIFT/RETURN_MERCHANDISE 等）和 incoterm（DDU/DDP）
5. 批量处理：CSV 导入 → CreateBatch → 轮询验证 → 确认购买 → PurchaseBatch，支持 500+ 单分批处理
6. 追踪：GetTrack 获取实时状态和历史事件，或注册 webhook 接收 track_updated 推送
显著优点
- 官方托管：Shippo 官方维护，OAuth 安全授权，无本地密钥泄露风险
- 多承运商聚合：统一接口覆盖 USPS、UPS、FedEx、DHL 等 30+ 承运商，自动折扣费率
- 功能完整：从地址解析、运费比价、标签生成、海关申报到批量发货、成本分析全链路覆盖
- Webhook 支持：实时追踪状态推送，适合电商履约自动化
- 响应式元 API：4 个工具动态发现操作，便于集成路由和权限分离（读/写操作分开管控）
潜在缺点与局限性
- 实时计费风险：
CreateTransaction和PurchaseBatch直接扣费，误操作不可撤销（部分 label 可 void，但 carrier 依赖且有时限） - 字段版本混杂：v1 字段名（
street1、zip）与 v2 字段名（address_line_1、postal_code）并存，CreateShipment 必须用 v1，CreateAddress/ValidateAddress 用 v2，易混淆 - 尺寸重量类型陷阱：所有数值必须为字符串，数字会导致失败
- Rate 7 天过期：旧 rate 无法直接购买，需重新创建 shipment
- MCP 层包裹复杂性：响应包裹在 Speakeasy envelope 中，部分错误绕过 envelope 直接以 MCP error 返回，需双路径处理
- 已知功能缺口：Packing slip 无 MCP 工具，需 fallback 到 REST API
适合人群
- 电商卖家、DTC 品牌需要多承运商比价和自动化标签生成
- 物流运营团队处理批量发货（CSV 导入）和成本优化分析
- 开发者集成 Shippo 到自有系统，需要地址验证、追踪 webhook、海关申报等高级功能
- 需快速上线、不愿自建承运商对接的中小企业
常规风险
- 财务风险：每次购买均为真实扣费，必须在代码/交互层强制确认流程，禁止自动购买
- 数据隐私：地址、包裹内容、商业数据经 Shippo 服务器处理，需符合 Shippo 隐私政策
- OAuth 会话过期：401 错误需重新授权，自动化流程需处理 token 刷新
- 海关合规：国际 shipment 的 HS code、申报价值、incoterm 错误可能导致清关延误或罚款
- 地址错误成本：未验证地址是导致 "no rates" 和标签失败的首要原因，必须前置验证
- 测试/生产环境隔离：Shippo 区分 test/live 模式，对象 ID 不互通，误操作可能导致生产数据污染或测试扣费