Shippo（配送手配プラットフォーム）統合の設計判断をガイドします。具体的には、以下の選択肢を検討するのに役立ちます： - **料金表示の方法**：チェックアウト時の送料表示か、それとも配送情報と取引記録の完全な管理か、または一括処理か - **住所検証の戦略**：古いバージョンのフィールドか新しいバージョンか - **配送タイプの選択**：国内取引か国際取引か（税関申告や国際取引条件の検討を含む） - **送り状の形式選択** - **ウェブフック設定**（自動通知機能） 次のような場合に使用：Shippo統合を計画・構築・検討するあらゆる場面。チェックアウト機能の開発、大量注文処理パイプラインの構築、住所検証、送り状生成、荷物追跡、税関対応、ウェブフック購読設定など。
Guides Shippo integration decisions, choosing between Rates at Checkout vs. full Shipments+Transactions vs. Batch processing, address validation strategy (v1 vs v2 fields), domestic vs international workflows (customs declarations, incoterms), label format selection, and webhook setup. Use when planning, building, or reviewing any Shippo integration, including building checkout flows, bulk fulfillment pipelines, address validation, label generation, package tracking, customs handling, or webhook subscriptions.
<!-- 自動生成されたドキュメント。このファイルを直接編集しないでください。 scripts/sync.js により skills/shippo-best-practices/SKILL.md から自動生成されています。 編集内容は次回の同期で上書きされます。 内容を変更するには、ソース ファイルを編集してから同期スクリプトを再実行してください。-->
最新の Shippo API バージョン: 2018-02-08。Shippo-API-Version ヘッダーで指定して送信してください。
https://mcp.shippo.com にホストされた Shippo MCP は、基礎となる個別の操作ではなく、正確に 4 つのツール（メタAPI）を提供します:
shippo_list_tools: 必要な操作を見つけます。shippo_describe_tool: その操作の入力形式を取得します。shippo_read_execute_tool: 読み込み操作（一覧取得、取得、検索）を実行します。shippo_write_execute_tool: 書き込みや変更操作（作成、購入、キャンセル）を実行します。このスキル内のすべての操作名（ValidateAddress（住所検証）、CreateShipment（配送作成）、CreateTransaction（取引作成）、GetTrack（追跡情報取得）など）は、ツールとして直接呼び出さず、これらのラッパーを 経由して 呼び出されます。
標準的な見つけ方は: shippo_list_tools で操作を探し、次に shippo_describe_tool でその形式を確認して、最後に shippo_read_execute_tool または shippo_write_execute_tool で実行します。読み込みと書き込みを分けることで、承認ポリシーが変更操作を別々に制御できます。
Claude アプリでは、これら 4 つのツールが遅延読み込み（必要に応じて読み込み）される可能性があるため、最初に「ツールがまだ読み込まれていません」というメッセージが出るのは正常です。操作名を推測するのではなく、ラッパーを使って見つけましょう。
| 構築内容 | 推奨される機能 | 参照ドキュメント |
|---|---|---|
| チェックアウト画面でリアルタイム送料表示 | Rates at Checkout | 料金計算（+ shippo/references/rate-shopping-guide.md） |
| 単一ラベルの購入 | Shipments + Transactions | ラベル購入 |
| CSV からの一括ラベル生成 | Batches + Manifests | 一括配送（+ shippo/references/csv-format.md） |
| 複数キャリアのパッケージ追跡 | Tracking + webhooks | 追跡 |
| 保存前にユーザー住所を検証 | Addresses v2 | 住所検証（+ shippo/references/address-formats.md） |
| 配送費用の分析・キャリア最適化 | Shipments + Transactions list | 配送分析 |
| 国際配送 | Customs Items + Declarations | ラベル購入（+ shippo/references/customs-guide.md + shippo/references/international-shipping.md） |
統合に関する質問やコード記述の前に、関連するスキルまたはリファレンスを必ず読んでください。
CreateTransaction の前に、キャリア・サービス・費用・配達予定日を表示して、明示的な承認を得てください。"10" を使い、10 は使わないでください。ShipmentId、TransactionId、OrderId）。shippo_describe_tool から得た正確な名前を使い、スネークケース（アンダースコア区切り）で推測しないでください。List* 操作で ID を確認してください。「内部エラーが発生しました。後でお試しください。」というメッセージは、多くの場合も入力の問題に起因するため、入力を検証してから再試行し、同じ呼び出しは最大 1 回のみ再試行してください。MCP はレスポンスを Speakeasy エンベロープでラップします。一部の失敗はエンベロープをバイパスします。解析ロジックとエラー処理パターンについては shippo/references/response-envelope.md と shippo/references/error-reference.md を参照してください。
https://mcp.shippo.com にホストされた MCP はユーザーごとの Shippo OAuth を使用します。Shippo 経由で一度認証する（Claude Code で /mcp を実行してサインイン）と、セッションが自動的に更新されます。コピーや設定は不要です。接続後は、以下のワークフローガイダンスは変わりません。
"Token does not exist": 認証情報が無効、失効、または別のアカウントのものです。Shippo OAuth セッションを再度認証してください。"Authentication credentials were not provided": 認証情報が Shippo に到達していません。OAuth セッションがまだ認証されていないか、期限切れです。Shippo OAuth セッションを再度認証してください。ラベルと一括購入は認可された Shippo アカウントから実際に課金されます。CreateTransaction または PurchaseBatch の前に、キャリア・サービスレベル・費用・配達予定日を表示し、ユーザーの明示的な承認を得てください。承認なしに進めないでください。
（Mintlify マイグレーション完了後、.md URL サフィックスは AI エージェント向けの生マークダウンアクセスを提供します。）
<!-- ⚠️ DO NOT EDIT. Auto-generated from skills/shippo-best-practices/SKILL.md by scripts/sync.js Edits here will be overwritten on the next sync. To change this content, edit the canonical source and re-run the sync script. -->
Latest Shippo API version: 2018-02-08. Send via the Shippo-API-Version header.
The hosted Shippo MCP at https://mcp.shippo.com exposes exactly 4 tools (a meta-API), not the underlying operations directly:
shippo_list_tools: discover which operation you need.shippo_describe_tool: get that operation's input schema.shippo_read_execute_tool: run a read (lists, gets, lookups).shippo_write_execute_tool: run a write or mutation (creates, purchases, voids).Every operation name in this skill (ValidateAddress, CreateShipment, CreateTransaction, GetTrack, etc.) is invoked through these wrappers, never called as a tool on its own. Standard discovery pattern: shippo_list_tools to find the operation, then shippo_describe_tool for its schema, then shippo_read_execute_tool or shippo_write_execute_tool to run it. The read/write split lets approval policies gate mutations separately. In the Claude apps these 4 tools may be deferred (loaded on demand), so an initial "tool has not been loaded yet" is normal: discover via the wrappers rather than guessing operation names.
| Building… | Recommended primitive | See |
|---|---|---|
| Checkout flow with live shipping rates | Rates at Checkout | Rate Shopping (+ shippo/references/rate-shopping-guide.md) |
| Single label purchase | Shipments + Transactions | Label Purchase |
| Bulk label generation from CSV | Batches + Manifests | Batch Shipping (+ shippo/references/csv-format.md) |
| Track packages across carriers | Tracking + webhooks | Tracking |
| Validate user addresses before save | Addresses v2 | Address Validation (+ shippo/references/address-formats.md) |
| Analyze shipping spend / optimize carriers | Shipments + Transactions list | Shipping Analysis |
| International shipments | Customs Items + Declarations | Label Purchase (+ shippo/references/customs-guide.md + shippo/references/international-shipping.md) |
Read the relevant skill or reference before answering integration questions or writing code.
CreateTransaction. Show carrier/service/cost/eta and require explicit user confirmation."10", never 10.ShipmentId, TransactionId, OrderId). Use the exact name from shippo_describe_tool; do not guess snake_case.List* operation first. The generic An internal error occurred. Please retry later. relay most often traces to an input issue too, so verify inputs before retrying, and retry the identical call at most once.The MCP wraps responses in a Speakeasy envelope. Some failures bypass the envelope. See shippo/references/response-envelope.md and shippo/references/error-reference.md for parsing logic and error-handling patterns.
The hosted MCP at https://mcp.shippo.com uses per-user Shippo OAuth. You authorize once through Shippo (in Claude Code, run /mcp and sign in), and the session refreshes automatically. There is nothing to copy or configure. Once you are connected, the workflow guidance below is unchanged.
"Token does not exist": the credential is invalid, revoked, or for a different account. Re-authorize the Shippo OAuth session."Authentication credentials were not provided": no credential reached Shippo. The OAuth session is not authorized yet, or it has expired. Re-authorize the Shippo OAuth session.Label and batch purchases charge the authorized Shippo account for real money. Before any CreateTransaction or PurchaseBatch, show the carrier, service level, cost, and ETA, and get explicit user confirmation. Do not proceed without it.
(Once Mintlify migration completes, .md URL suffixes will provide raw markdown access for AI agents.)
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。