Inventory MCP - Droplinked Developers

The Inventory MCP is Droplinked’s agentic surface over InventoryOS. Any MCP-capable agent (Claude, ChatGPT, Cursor, Continue, the Vercel AI SDK, …) can discover merchant catalogs, compose carts, place orders, issue refunds, and read trust-fabric state — served directly by the Droplinked backend (apiv3), no extra gateway and (in the current phase) no credentials required for the public tools. Discovery doc (live):

curl -s https://apiv3.droplinked.com/.well-known/mcp.json | jq '.tools[].name'

This page is grounded in the live tool registry (McpToolRegistryService). The discovery doc at /.well-known/mcp.json is always the canonical source of truth for the exact tool names, descriptions, and JSON-schema input shapes — if this page and the discovery doc disagree, the discovery doc wins.

Transport + protocol

The backend speaks MCP over HTTP. See MCP Server for the full transport reference. In short:

Surface	Method + path	Auth
Global discovery doc	`GET /.well-known/mcp.json`	Public
Per-shop discovery doc	`GET /shop/{shopUrl}/.well-known/mcp.json`	Public
List tools	`POST /mcp/v1/tools/list`	Public
Call a tool	`POST /mcp/v1/tools/call`	Public (admin tools gated by an `_adminKey` argument)
List resources	`POST /mcp/v1/resources/list`	Public
Read a resource	`POST /mcp/v1/resources/read`	Public

All /mcp/v1/* routes accept both a flat body ({ name, arguments }) and a JSON-RPC 2.0 envelope ({ jsonrpc: "2.0", id, method, params }) — the shape every official MCP client sends. The response mirrors the request shape. The advertised protocolVersion is 2024-11-05.

The tool registry

The registry currently exposes 25 tools. Tools are read-only unless marked write. Three observability/diagnostic tools are admin-gated: they require an _adminKey argument that matches the server’s MCP_ADMIN_SECRET.

Catalog + discovery (read-only)

Tool	Purpose
`searchProducts`	Free-text search across the public Droplinked catalog (matches product title).
`findInventory`	SKU-availability-aware multi-source query (`native` + live `impact_brand` + `any`) — returns `stock_state`, `source`, `priceCents`, `currency`, `imageUrl`, `productUrl`, an optional Model-A `trackedBuyUrl`, and a (policy-redacted) attestation status. Designed for cart composition + multi-brand discovery. See below.
`getProductDetail`	Full product detail for a `shopUrl` + `productSlug` — images, all SKUs (price + inventory), metadata.
`getShopInfo`	Public shop metadata — name, description, currency, logo, social links.
`listMerchants`	List active merchants (as their public shops), optional ISO-3166 country filter.
`getStockoutAlerts`	SKUs at stockout risk for a shop, severity-filtered. Attestation-policy-aware.
`getInventoryHealth`	One-shop inventory posture snapshot — total SKUs, stockouts, low-stock, attestation status, synced connectors.
`estimateIntakeCost`	Estimate the monthly infra cost of adding N SKUs to a merchant’s Droplinked catalog.

Merchant discovery — opt-in only (read-only, except where noted)

These tools only surface merchants who have set agenticDiscoveryEnabled: true. See Merchant Discovery Rules.

Tool	Purpose
`searchMerchants`	Search opted-in merchants by query / category / geo / currency.
`getMerchantDirectory`	Paginated directory of opted-in merchants.
`getMerchantCatalogSummary`	Catalog snapshot for an opted-in merchant — product count, top categories, currency, shipping geos.
`recordAgenticIntent`	Write. Log an external agent’s intent (`browse` / `buy` / `compare` / `share`) against an opted-in merchant. Feeds the attribution ledger. Idempotent on an optional `intentId`.

Cart + order (write, except reads)

Tool	Purpose
`cartAdd`	Write. Add a line to a cart (or create a cart for a shop).
`cartUpdateLine`	Write. Change quantity on an existing cart line.
`cartRemoveLine`	Write. Remove a line from a cart.
`cartApplyDiscount`	Write. Apply a discount / coupon code to a cart.
`placeOrderAgentic`	Write. Compose an order from `[{skuId, quantity}]` + email; optionally resolve the payment-intent in the same call (PSP-invisible).
`getOrderReceipt`	PII-free, PSP-invisible order receipt — line items, totals, payment state, fulfillment.
`getOrderStatus`	Lightweight order state-machine projection for polling — status, payment state, fulfillment, tracking.
`refundOrder`	Write. Issue a refund; the PSP is resolved automatically from the order record.

Trust + financing (read-only)

Tool	Purpose	Notes
`recommendLender`	Recommend active lenders for a jurisdiction (exact match first, then `GLOBAL`).	See Lender Trinity MCP Tools.
`getUnderwritingSignals`	Composite underwriting read — Schema B credit-risk + Schema C repayment history + tier upgrade preview.	Privacy-gated to opted-in merchants. See Underwriting MCP Tools.
`traceAttestationLineage`	Walk the cross-schema EAS attestation lineage tree for a merchant.	Admin-gated (`_adminKey`).

Observability / diagnostics (admin-gated, read-only)

Tool	Purpose
`queryEventLog`	Query the EventBus event log (merchant / type / time-range, keyset-paginated). Requires `_adminKey`.
`getInventoryDrift`	Compare Droplinked-mirrored inventory against the Shopify Admin API source of truth. Requires `_adminKey`.

Tool annotations (preview)

The MCP spec lets a server tag each tool with behavioural hints so a client can reason about safety before calling — readOnlyHint (does not mutate state), destructiveHint (may perform an irreversible update), and openWorldHint (touches an external system). These annotations ship alongside the Streamable HTTP transport (gated behind MCP_STREAMABLE_HTTP_ENABLED, preview) — the current /mcp/v1/* tools/list response does not yet include them, so treat this table as the planned classification:

Class	Tools	`readOnlyHint`	`destructiveHint`
Read-only discovery / fetch	`findInventory`, `searchProducts`, `searchMerchants`, `getProductDetail`, `getShopInfo`, `getOrderReceipt`, `getOrderStatus`, `getStockoutAlerts`, `getInventoryHealth`, `getInventoryDrift`, `getUnderwritingSignals`, `getMerchantDirectory`, `getMerchantCatalogSummary`, `listMerchants`, `traceAttestationLineage`, `recommendLender`, `estimateIntakeCost`, `queryEventLog`	`true`	—
Recoverable writes	`cartAdd`, `cartUpdateLine`, `cartRemoveLine`, `cartApplyDiscount`, `recordAgenticIntent`	`false`	—
Destructive writes (money moves)	`placeOrderAgentic`, `refundOrder`	`false`	`true`

findInventory and getInventoryDrift additionally carry openWorldHint: true (they reach Impact / the Shopify Admin API).

About `findInventory`

findInventory is the cart-composition + multi-brand discovery primitive — it queries across inventory sources and returns each match with stock state, price, image, and a buyable product URL, so an agent can build a cart across results. The source argument selects the inventory source: native, impact_brand, rakuten, or any (union, deduplicated by SKU):

native — the Droplinked catalog (published, visible, purchasable ProductV2 / ProductSkuV2). Always live.
impact_brand — the live multi-brand discovery path. When IMPACT_LIVE_SEARCH_ENABLED=true, findInventory proxies Impact’s live Catalogs/ItemSearch endpoint over the full multi-brand advertiser catalog (keyword-matched as Name~"<query>"), with a thin ~6h per-keyword cache and zero bulk replication. This is how an agent reaches brands like Walmart or Lids through the same findInventory call. The path is fail-open: on a rate-limit (Impact’s quota is hourly) or any upstream error it serves a stale cache hit if present, otherwise degrades to native results — it never breaks the call. With the flag off, impact_brand returns no live rows and the call falls back to native results.
rakuten — reserved for the Rakuten feed; returns no rows until that source is wired.

When an intentId (from recordAgenticIntent) is supplied and IMPACT_ATTRIBUTION_ENABLED is on, each impact_brand result is enriched with a Model-A trackedBuyUrl — a tracked deep-link the agent should drive the buyer to, so the advertiser’s pixel credits Droplinked (publisher), tagged subId1=dl-agentic:{intentId}. Enrichment is per-item fail-open: a link-gen failure returns the product without a trackedBuyUrl rather than dropping it. See Attribution + Commission. The per-item attestation field is a privacy-redacted status (unattested by default for external impact_brand items, which carry no native attestation) and respects each merchant’s attestation policy for native items, so it never over-discloses. When DISCOVERY_RANKER_ENABLED=true, results are re-ordered by their merchant’s attestation-weighted trust score (and each item carries a trustScore). With the flag off, results come back in source order.

curl -s -X POST https://apiv3.droplinked.com/mcp/v1/tools/call \
  -H 'content-type: application/json' \
  -d '{
    "name": "findInventory",
    "arguments": { "query": "beanie", "inStockOnly": true, "limit": 5 }
  }' | jq '.content[0].text | fromjson'

Multi-brand Impact catalog

The large multi-brand affiliate catalog (Flatlay × Impact Partner REST) is reachable two ways:

Through findInventory (source: impact_brand / any) — the public MCP path. When IMPACT_LIVE_SEARCH_ENABLED=true this proxies Impact’s live Catalogs/ItemSearch over the whole multi-brand advertiser catalog (keyword Name~"<query>"), query-time, never bulk-replicated, with a thin ~6h per-keyword cache. This is the primary agent-facing path and is described in About findInventory above.
Through a merchant-authenticated connector — a separate, not public surface for a merchant to manage their own Impact connection. It is read-only, query-time (never bulk-replicated), and rate-limited per merchant.

Endpoint	Purpose
`POST /connectors/impact/connect`	Connect a merchant’s Impact `accountSid` + `authToken` (validated before persisting, encrypted at rest).
`GET /connectors/impact/status`	Connection state + imported brand count.
`GET /connectors/impact/brands`	Imported brand metadata for the merchant.
`GET /connectors/impact/items`	Query catalog items in real time (filter by `brandId`, `search`, paginated).

All four connector endpoints require a merchant JWT (PRODUCER role). The connector never exposes write methods, even when the token carries RW scope.

Privacy + cost-efficiency

Inventory + attestation tools respect each merchant’s MerchantAttestationPolicy:

Default: private — merchants who have not opted in see a redacted attestation status.
lenders_only scope — visible to allowlisted lenders.
public scope — visible to anyone.

Merchant-discovery tools (searchMerchants, getMerchantDirectory, getMerchantCatalogSummary, recordAgenticIntent) hard-filter on agenticDiscoveryEnabled — non-opted merchants are invisible, and recordAgenticIntent returns opt_in_required rather than writing a ledger row.

Where to go next

MCP Server — full transport reference + how to connect Claude / ChatGPT / Cursor
Attribution + Commission — how agentic conversions settle
Merchant Discovery Rules — opt-in + tiering
Storefront MCP Discovery — per-shop discovery doc
InventoryOS concept — the architectural model underneath

​Transport + protocol

​The tool registry

​Catalog + discovery (read-only)

​Merchant discovery — opt-in only (read-only, except where noted)

​Cart + order (write, except reads)

​Trust + financing (read-only)

​Observability / diagnostics (admin-gated, read-only)

​Tool annotations (preview)

​About findInventory

​Multi-brand Impact catalog

​Privacy + cost-efficiency

​Where to go next

Transport + protocol

The tool registry

Catalog + discovery (read-only)

Merchant discovery — opt-in only (read-only, except where noted)

Cart + order (write, except reads)

Trust + financing (read-only)

Observability / diagnostics (admin-gated, read-only)

Tool annotations (preview)

About `findInventory`

Multi-brand Impact catalog

Privacy + cost-efficiency

Where to go next