> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droplinked.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Inventory MCP
> Droplinked's Model Context Protocol surface — the live tool registry any AI agent can discover and call against the apiv3 backend.
The **Inventory MCP** is Droplinked's agentic surface over [InventoryOS](/concepts/inventory-os).
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):
```bash theme={null}
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](/agentic/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](#about-findinventory). |
| `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](/agentic/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](/agentic/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](/agentic/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](/agentic/mcp-server#planned-streamable-http) (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~""`), 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](/agentic/attribution-and-commission#external-impact-advertiser-path).
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.
```bash theme={null}
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:
1. **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-time, never
bulk-replicated, with a thin \~6h per-keyword cache. This is the primary agent-facing path
and is described in [About `findInventory`](#about-findinventory) above.
2. **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](/agentic/mcp-server) — full transport reference + how to connect Claude / ChatGPT / Cursor
* [Attribution + Commission](/agentic/attribution-and-commission) — how agentic conversions settle
* [Merchant Discovery Rules](/agentic/merchant-discovery-rules) — opt-in + tiering
* [Storefront MCP Discovery](/agentic/storefront-mcp-discovery) — per-shop discovery doc
* [InventoryOS concept](/concepts/inventory-os) — the architectural model underneath