Identify the CLI as the caller via X-Shopify-Agent-Source header

[joerj123]

What

Send an X-Shopify-Agent-Source: shop-cli header on every outbound MCP request so the catalog / UCP endpoints can attribute Shop CLI traffic server-side.

The header is added in the single callMcp chokepoint in src/shop-client.ts, so it rides on all MCP calls — global-catalog reads (search_catalog, lookup_catalog, get_product) and per-shop UCP checkout calls — for both authenticated and unauthenticated requests. The caller's own headers are spread last so an explicit override always wins.

Why

We're moving the Shop Skill (and other surfaces) to call the Global Catalog MCP endpoint directly instead of going through the Shop Proxy. Today, unauthenticated catalog calls carry no client_id and collapse into a single anonymous bucket keyed only by source IP — so we can't say "X searches came from Shop CLI" and we lose top-of-funnel attribution.

Per the Slack discussion, the agreed approach is a transport header rather than a UCP schema/API change: it's orthogonal to the protocol, invisible to the public UCP contract, trivial for first-party clients to set, and trivial to log into the existing tool-call Monorail event server-side. This PR is the client half of that; the server side picks the header up and adds it to the Monorail event.

Important caveat

The value is self-asserted analytics/funnel metadata only. It is spoofable, so it must never feed trust, fraud, or rate-limiting decisions — those stay keyed on auth tier + IP. Documented as such in references/catalog-mcp.md and the code comments.

Naming note: the thread proposed X-Shopify-Agent-Source with snake_case values (shop_skill, ucp_cli, …). I used the kebab value shop-cli to match the repo/package name and the request. Happy to switch to shop_cli (or another header name) if that's the convention the server-side logging lands on.

Changes

• src/constants.ts — add AGENT_SOURCE_HEADER (X-Shopify-Agent-Source) and AGENT_SOURCE (shop-cli).
• src/shop-client.ts — inject the header into callMcp.
• tests/catalog.test.ts — assert the header is sent on catalog calls.
• references/catalog-mcp.md — document the header.
• changeset (minor).

Testing

• pnpm typecheck ✅
• pnpm test ✅ (80 passing, including the new case)
• pnpm build ✅