UCP 2026-08-25 から、Shopify ストアフロントの MCP エンドポイントで search_locations / lookup_locations の 2 ツールが使えるようになった。店名・都市・距離・取扱商品でマーチャントの実店舗を絞り込める。任意で使う新機能なので、使わないなら対応は不要。
dev.ucp.common.location.search / dev.ucp.common.location.lookup）に対応した。UCP 経由のエージェントから、マーチャントの実店舗情報を引く手段としてこの 2 ツールは提供されていなかった。
ストアフロント MCP エンドポイントに search_locations と lookup_locations が出てくる。任意の新機能で、使わなければ変更不要。
https://{storedomain}/api/ucp/mcp。
pagination.limit で最大 250 件pagination.cursor を渡すgid://shopify/Location/123batch_limit_applied メッセージ| 項目 | 仕様 | 注意点 |
|---|---|---|
| search の件数 | 既定 10 pagination.limit で最大 250 |
次ページは pagination.cursor |
| lookup の ID 数 | 最大 10（重複除外後） | 超過時は batch_limit_applied が返るので分割送信 |
| filters.items | 最大 10 商品バリアント ID | 全バリアントが取り扱い可能な店舗だけがマッチ（AND 条件） |
| distance | 明示的な center ＋ 最大半径（メートル） | 中心点は買い手が共有した位置のみ。Shopify は文脈や IP から推定しない |
| query | 店名・都市にマッチ | — |
| 商品マッチの意味 | 既存の店舗在庫表示（store availability）ルールに従う | 在庫数ではない 受け取り保証・取り置きでもない |
営業時間での絞り込み。
店舗設備での絞り込み。
独自のフィルタ条件。
distance 以外のリレーション。
invalid_input エラーになる。また、選択した店舗での受け取り（Pickup）チェックアウトは非対応。ストアフロント MCP エンドポイントを UCP 2026-08-25 で使い、location ケーパビリティのどちらかをネゴシエーションするプラットフォーム／エージェント。
retail location の無いショップ（ケーパビリティもツールも掲載されない）。ケーパビリティを宣言しない、または以前の UCP バージョンでネゴシエーションする連携。
dev.ucp.common.location.search と .lookup を version 2026-08-25 で宣言。
ショップのプロファイルに掲載されているときだけロケーションツールを呼ぶ。
distance.center は買い手が共有を選んだ位置からのみ送る。
商品マッチは暫定扱い。「用意できています」と伝える前に在庫と配送方法を確認。
retail location の無いショップではケーパビリティもツールも出てこない。/.well-known/ucp のプロファイルを見て、掲載がある場合だけツールを呼ぶ実装にする。
hours / amenities / カスタムフィルタ / serves は無視されず invalid_input。汎用 UCP クライアントを使い回す場合、Shopify 向けにはこれらを外して送る。
search は既定 10・最大 250 件、カーソルで続きを取得。lookup は重複除外後 10 ID まで、超過は batch_limit_applied を見て分割再送。
distance.center は買い手が共有を選んだ位置からのみ。Shopify も文脈や IP から中心点を推定しない。プライバシー設計上の前提として扱う。
最大 10 バリアントの AND 条件で、既存の店舗在庫表示ルールに従う。在庫数でも受け取り保証でも取り置きでもない。さらに選択店舗での Pickup チェックアウトは非対応なので、エージェントの応答文言は「在庫がありそうな店舗」止まりにし、確定はカート／チェックアウトで行う。
search_locations に distance（中心点＋半径メートル）を渡し、近隣店舗を名前・住所付きで提示。filters.items に入れて検索。全バリアントが取り扱い可能な店舗だけが返る。search_locations を pagination.limit 250 ＋カーソルで全件取得。以降は保存した ID を lookup_locations で再取得。batch_limit_applied を検知したら残りを再送。geo はマーチャントが設定した場合のみなので欠損を許容する。