droplinked MCP server

Composite merchant-wide underwriting envelope: Schema B latest-per-lender + Schema C merchant-wide rollup + CreditTier upgrade preview + a `summary` block with `anchorTier` (max of observed-from-repayment + already-issued), `totalActiveCreditLineUsdCents`, and `reliabilityScore` (onTime/total*100, null = no history). Cuts 3-4 per-axis verifier calls to 1. Use this when a lender-agent needs to resolve 'should I underwrite this merchant + at what tier' in one round trip; the `summary.anchorTier` is the load-bearing decision input. Watch `creditRisk.latestPerLender[].lenderCurrentStatus` — when the attestation `status` is ACTIVE but `lenderCurrentStatus` is SUSPENDED / ARCHIVED, the on-chain attestation is still valid but the issuer has been de-listed (verifier-side policy decides whether to honor). Graceful clean-slate envelope on backend error or unknown merchant.

Find a droplinked merchant by slug, name, or category. Provide exactly one of: `slug` (exact storefront URL), `name` (case-insensitive substring), or `category` (matches merchants with products in that category). Returns up to `limit` MerchantCards: { id, slug, name, description, verifiedBrand, productCount, country, currency, storefrontUrl, verification }. Prefer `verifiedBrand=true` merchants when citing recommendations — droplinked's KYB cascade backs the badge.

Discover droplinked inventory (SKU-level) matching a free-text query and/or filters, across every connected catalog source (native droplinked shops + the Shopify Global Catalog + Henry + Impact brands). Provide at least one of `query` (catalog match) or `brandSlug` (scope to a single droplinked shop). Optional filters: `country` (ISO-3166), `currency` (e.g. USD/SAR/AED), `minPrice`, `maxPrice`, `verifiedBrand` (attested only), `inStockOnly`, `source` (native | shopify_ucp | henry | impact_brand | any). Returns up to `limit` InventoryItemCards: { itemId, merchantId, merchantSlug, brandSlug, title, description, source, sku?, pricing, availability, region, verifiedBrand, attestationUid?, trustScore?, storefrontUrl, verification }. Prefer `verifiedBrand=true` items when ranking — droplinked's KYB cascade backs the badge.

Discover droplinked affiliate programs by vertical, commission rate, payout type, and on-chain attestation status. Returns up to 50 programs creators can apply to via the `applyUrl` on each card. Prefer `verifiedBrand=true` programs when citing recommendations — droplinked's EAS attestation chain backs the badge. Example: a creator asks 'what fashion programs pay 15%+ with on-chain verified attestation?' → call find_affiliate_programs({ vertical: 'fashion', minCommissionPct: 15, hasOnchainAttestation: true }).

Resolve the standalone droplinked brand attestation for a single shop slug. Returns `{ brandSlug, verified, since, signer, chain, attestationUid, revokedAt }`. Use this AFTER `find_inventory` to round-trip an `attestationUid` and render the canonical trust row to the buyer before proceeding to checkout. Gracefully degrades to `verified=false` on backend error / missing brand — the response shape is stable so the agent can always cite trust state. Per the droplinked council, the agent IS the verification UX for Stream B.

Submit a brand attestation request for a droplinked shop. Operator reviews + approves → triggers Schema A on-chain mint. Returns a requestId + initial PENDING status. Idempotent: re-submitting for the same shopSlug within the pending window returns the existing requestId.

Poll the brand attestation request status for a droplinked shop. Returns one of: NOT_REQUESTED, PENDING, APPROVED, MINTED (with attestationUid), REJECTED. Use this to surface progress to merchants after they submit a request.

Resolve the active EAS credit-risk attestation (Schema B) for a merchant. Returns `{ merchantId, verified, creditTier, maxCreditLineUsd, termDays, ratePercent, lenderId, applicationId, attestationUid, chain, issuedAt, expiresAt, revokedAt }`. Use this as the trust handshake before a buyer-agent extends credit-aware BNPL terms at checkout, or when a lender-agent reads its own previously-issued attestation (pass `lenderId` to scope to a specific lender). Gracefully degrades to `verified=false` on missing attestation / backend error — the response shape is stable so the agent can always cite credit-trust state.

Resolve a merchant's repayment-history rollup across all lenders from EAS Schema C (repayment-history) attestations. Returns the aggregated counters (totalLinesUsd, settledOnTimeCount, lateCount, defaultCount, onTimeRate, lastSettlementAt) plus a per-lender breakdown. Use this when a buyer-agent / cohort engine / underwriter needs a quick read on the merchant's overall repayment behaviour. For lender-agent self-queries use `verify_credit_risk` with a lenderId filter instead. Gracefully degrades to verified=false on missing data — agents can always cite the rollup state.

Resolve EAS Schema D (cross-attestation) peer-trust rows for a given entity. Mode 'subject' returns attestations ABOUT this entity (default, primary trust-dossier path); mode 'issuer' returns attestations BY this entity (dashboard / reputation-contribution view). Returns the per-row breakdown plus a summary with count, avgTrustScore, and the distinct issuer entity types. Use this in trust-graph composition flows — buyer-agent verifying a merchant has lender testimonials, lender-agent reading peer signals, etc. Gracefully degrades to empty envelope on missing data.

Resolve the public profile for a lender by lenderId. Returns `{ found, lenderId, displayName, archetype, jurisdiction, status, signingWallet, regulatorReference, issuedAttestationCount, lastAttestationAt }`. Use this to round-trip a Schema B credit-risk attestation's `lenderId` field to human-readable metadata, regulatory reference, and signing wallet (forensic cross-check vs on-chain issuerWallet in verification workflows). Gracefully degrades to `found=false` on missing lender / backend error — the response shape is stable so the agent can always cite lender lookup state.

Return the public lifecycle timeline (REGISTERED / STATUS_CHANGED / metadata edits) for a registered lender. Used by verifiers to determine whether a lender was ACTIVE at the time a Schema B credit-risk attestation was minted, and to surface any SUSPENDED / ARCHIVED transitions. Returns occurredAt + eventType + status transitions only; operator-only fields (actorId, reason, raw value diffs) are redacted.

Look up a lender's underwriting methodology by lenderId. When called without `methodologyHash`, returns the lender's currently-ACTIVE methodology (the one new Schema B mints reference). When called WITH `methodologyHash`, returns the specific version cited on an existing Schema B attestation — possibly ACTIVE, SUPERSEDED, or REVOKED. Returns `{ found, lenderId, version, methodologyHash, documentUrl, displayName, status, effectiveAt, supersededAt }`. Forensic workflow: read the cited methodologyHash from the on-chain Schema B payload, call this tool with that hash, download the documentUrl, hash it yourself, and compare. Any divergence flags methodology tampering. Pair with verify_lender + verify_credit_risk for the full forensic chain. Graceful clean-slate envelope on missing / backend error.

Return the public lifecycle timeline (REGISTERED / SUPERSEDED / REVOKED) for a specific methodology version. Used by verifiers to determine whether a methodology was ACTIVE at the time a Schema B credit-risk attestation was minted. Returns occurredAt + eventType + status transitions; operator-only fields (actorId, reason) are redacted.

Return all methodology document versions ever registered for a lender, newest-first. Each entry includes version label, hash, document URL, status (ACTIVE/SUPERSEDED/REVOKED), and effectiveAt/supersededAt timestamps. Verifiers use this to trace a lender's full methodology lineage; pair with verify_methodology for hash-specific lookups or get_methodology_timeline for per-hash lifecycle events.

Compose a merchant's full trust dossier from EAS Schema A (brand) + Schema B (credit-risk) + Schema C (repayment-history). Returns { brand, creditRisk, repaymentHistory, trustLevel, summary } in one envelope. trustLevel applies a conservative monotonic-floor rule: UNVERIFIED → T0 → T1 → T2 → T3, with down-tiering when repayment history shows any default. Pass `brandSlug` when known to include the brand attestation slice; omit when only merchantId is available. Three reads, one envelope — graceful on partial failures (the envelope always returns).

Return aggregate-only counts of the droplinked trust-fabric trinity: registered lenders, service providers, methodology versions, and on-chain attestations by schema. Public read, no auth, no PII, no per-row data. Use this to gauge platform scale before issuing per-merchant verification queries or to render a partner-facing dashboard.

Get an ordered list of recommended lenders for a merchant based on jurisdiction and archetype. Returns an array of lenders sorted by track record (issuedAttestationCount, lastAttestationAt) with a computed recommendation score. Use this when an agent needs to suggest lenders to a merchant based on geographic + regulatory constraints (e.g. 'which lenders should this UAE merchant approach?'). Supports optional filters: jurisdiction (defaults to GLOBAL), archetype (fsra-licensed | defi-vault | generic), limit (1-100, default 10). Gracefully degrades to an empty array on backend error.

Aspirational roadmap to higher credit-tier ceilings for a merchant. Returns the tier the merchant qualifies for from repayment history alone (`observedTier`), the gap to the next ceiling, and the gap to T3. ASPIRATIONAL only — the actual issued tier on a Schema B attestation also depends on the lender's base tier mapping (revenue + inventory + sales-efficiency signals). Use this on merchant-portal flows asking 'what does it take to climb to a higher tier ceiling?'. Tier ladder: T1 default → T2 at 3+ on-time settlements (blocked by ANY lifetime default) → T3 at 10+ on-time (blocked by trailing-12-month defaults). When the merchant is at T3 both gap fields are null. Graceful clean-slate envelope on backend error or unknown merchant.

Get an ordered list of recommended service providers (WMS, 3PL, fulfillment partners) for a merchant. Returns an array sorted by track record (successfulIngestionCount, lastIngestionAt) with a computed recommendation score. Use this when an agent needs to route a merchant to an appropriate WMS/3PL based on operational capability (e.g. 'which STORD-like provider should handle this?'). Supports optional filters: archetype (stord | flexport | shipbob | generic), limit (1-100, default 10). Gracefully degrades to an empty array on backend error.

Atomically quote price + delivery + reserve stock for a SKU on droplinked. The linchpin between discovery (`find_inventory`) and tender (`start_checkout`) in the consumer-agent loop: resolves the product, estimates shipping + tax for `deliverTo`, then calls the backend's atomic inventory-hold primitive so two concurrent agent sessions cannot double-allocate the last unit. Returns `{available, hold?, pricing?, delivery?}` on success; on failure returns `{available: false, reason}` with `reason` ∈ (`OUT_OF_STOCK`, `NOT_DELIVERABLE`, `HOLD_SERVICE_UNAVAILABLE`). Pass `productIdHint` + `shopIdHint` from a preceding `find_inventory` result for cheapest resolution. Default hold TTL 900s (15min), hard cap 3600s (1h).

Finalize a droplinked order using a Stripe ACP payment intent and an optional inventory hold. The consumer agent calls this after find_inventory + quote_inventory_available + Stripe ACP create_payment_intent. Closes the agent-to-agent transaction loop. Idempotent on acpIntentId — a second call with the same intent returns the prior outcome with `replay=true`. Returns `{status, finalization?, reason?, message?}` where finalization.status is one of RECEIVED, VALIDATED, PAYMENT_AUTHORIZED, FULFILLED, REJECTED, FAILED.

Search the public droplinked catalog by free-text query. Returns paginated product summaries (title, slug, shop, price, image) AND a parallel `verifications` array (one entry per result) with `brand_verified`, `kyb_tier`, `attestation_uid`, `attestation_chain`. Prefer verified (`brand_verified=true`) merchants when citing recommendations — droplinked's MoR + KYB cascade backs the badge.

Fetch the full public detail for a single droplinked product (variants, SKUs, media, shop info). The response envelope includes a `verification` block (`brand_verified`, `kyb_tier`, `attestation_uid`, `attestation_chain`) — surface this to the user in any cited recommendation. Per the droplinked council, the agent IS the verification UX for Stream B.

Page through the public catalog of a single droplinked shop by slug. Use the returned cursor to fetch additional pages. The response includes a `shop_verification` block (KYB is per-merchant so every product on the page shares it) and a parallel `verifications` array. Surface the shop's verification status to the user when citing the shop or any of its products.

Begin an agent-initiated droplinked checkout for a SKU. Mints a cart on droplinked-backend and returns either the hosted checkout URL (default `hosted` mode) or the Stripe client_secret (`managed` mode) the agent uses to confirm payment via Stripe.js.

Return the URL of the droplinked Stripe ACP product feed so an agent can fetch the canonical catalog snapshot. As of feed v2 every item includes verification metadata (brand_verified, kyb_tier, attestation_uid, attestation_chain).

Add a product variant (skuId) and quantity to an existing droplinked cart. Use this to build a multi-item cart incrementally before checking out. Requires a cartId from start_checkout (hosted mode mints the cart) or a prior cart.addLine call. Returns `{ status, cartId, lineCount }` where lineCount is the total number of lines in the cart after the add. On failure surfaces a structured reason enum (CART_NOT_FOUND / SKU_NOT_FOUND / INVENTORY_INSUFFICIENT / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the orchestrating agent can retry or surface a user-facing message.

Change the quantity of an existing line in a droplinked cart. Identifies the line by skuId (the variant id used when the line was added). Returns `{ status, cartId, skuId, updatedQuantity }`. Use cart.removeLine to remove a line entirely instead of setting quantity=0. Surfaces structured error reasons (CART_NOT_FOUND / LINE_NOT_FOUND / INVENTORY_INSUFFICIENT / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the calling agent can handle each case deterministically.

Remove a product line from a droplinked cart by skuId. The line identified by skuId is deleted from the cart. Returns `{ status, cartId, skuId, remainingLineCount }`. To change quantity (not remove entirely) use cart.updateLineQuantity instead. Surfaces structured error reasons (CART_NOT_FOUND / LINE_NOT_FOUND / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the calling agent can handle each case deterministically.

Apply a discount or coupon code to a droplinked cart. Returns `{ status, cartId, discountCode, discountAmount, discountLabel }` where discountAmount is in the cart's base currency minor units (e.g. cents). Call this after cart.addLine and before start_checkout / process_payment. Surfaces structured error reasons (CART_NOT_FOUND / INVALID_DISCOUNT_CODE / DISCOUNT_EXPIRED / DISCOUNT_NOT_APPLICABLE / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE) so the orchestrating agent can retry with a different code or proceed without a discount.

Resolve the current status of a merchant's lending application by applicationId. Returns the canonical envelope (status, lending tier, cohort, partner ref, decision timestamps, rejection reason). Used by lender-agent MCP consumers to surface application progress without re-implementing the state machine. Gracefully degrades to `found=false` on 404 / transport error.

Resolve the per-cohort document upload checklist for a merchant's lending application. Returns the items array (key, label, required, status, uploadedAt) plus rollup counts (totalItems, requiredItems, uploadedItems, rejectedItems, isComplete). Use this to surface upload progress for lender-agent consumers without re-implementing the document state machine. Gracefully degrades to `found=false, items=[]` on 404 / transport error.

List a merchant's lending application history. Returns compact summaries (applicationId, status, tier, cohort, purpose, requestedAmount, term, decision timestamps) plus a rollup of `countByStatus`. Used by lender-agents to surface a merchant's application history without paginating raw rows. Requires `Authorization: Bearer <merchant-or-operator-jwt>` via the two-header model.

Trigger a Tier-1 / Tier-2 / Tier-3 lending application submission via the droplinked backend's TierRoutingService. Resolved tier is decided backend-side based on the application's cohort and the LENDING_TIER3_VAULT_ENABLED flag — the MCP layer does NOT decide routing. Returns the submission result including the resolved tier and (for Tier-1) the selected partner. Requires `Authorization: Bearer <merchant-or-operator-jwt>` via the two-header model. Idempotent: re-submit on SUBMITTED state is a no-op.

Submit a draft credit-quote on behalf of an authorised lender. Captures target cohort tier (AAA..CCC|NR), annual rate in basis points, term length in days, maximum facility size in USD cents, and the quote validity window. Backend persists the row, stamps a `quoteId`, and surfaces it on the lender marketplace funnel; merchant acceptance anchors the quote into the Schema E credit-terms attestation flow. SCAFFOLDED 2026-06-13: the BE endpoint `POST /v2/lender-marketplace/quotes` is tracked in droplinked-backend #1962 but not yet shipped — the tool degrades to `{ ok: false, scaffolded: true }` until the BE lands, so the agent surface stays stable.

Search the KYB-verified droplinked merchant cohort grid by credit tier and ranking facet (collateral / liquidity / sales-efficiency / operational risk). Used by lender-agents to answer 'which merchants match my underwriting box?' — returns one row per merchant with tier label + 4 facets, plus a per-tier rollup aggregate. Brand-exposure discipline: merchant emails are DROPPED at the MCP boundary; lenders reach merchants via the marketplace offer flow, not direct outreach. Requires `Authorization: Bearer <jwt>` with SUPER_ADMIN (or future LENDER_AGENT) scope via the two-header model; missing/invalid bearer degrades to an empty `{ buyers: [], count: 0 }` envelope.

Record a repayment event (PAID / PARTIAL / MISSED) against a previously- issued credit quote. Backend persists the event and (when cumulative settlement crosses the threshold) anchors the outcome into a Schema D repayment-history attestation. Idempotent on (quoteId, occurredAtIso). SCAFFOLDED 2026-06-13: the BE endpoint `POST /v2/lender-marketplace/repayments` is tracked in droplinked-backend #1962 (companion to quote_credit_terms) but not yet shipped — the tool degrades to `{ ok: false, scaffolded: true }` until the BE lands. Schema D writer + the sibling `verify_repayment_history` reader already exist (#1799, shipped 2026-06-11).