{"name":"droplinked-mcp","version":"0.1.0","protocolVersion":"2024-11-05","transport":"http","origin":"https://mcp.droplinked.com","capabilities":{"tools":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"prompts":false},"endpoints":{"health":"https://mcp.droplinked.com/healthz","toolsList":"https://mcp.droplinked.com/mcp/tools","toolsCall":"https://mcp.droplinked.com/mcp/tools/{name}"},"auth":{"scheme":"x-mcp-api-key","header":"X-MCP-API-Key","identityPassthrough":{"header":"Authorization","format":"Bearer <consumer-agent-jwt>","description":"Two-header model: X-MCP-API-Key authorises the request to this MCP server; Authorization: Bearer carries the consumer agent's identity JWT and is forwarded verbatim to backend tools that require AgentIdentityGuard."}},"merchantDiscovery":{"pathTemplate":"https://mcp.droplinked.com/{shopSlug}/manifest","scopedToolsTemplate":"https://mcp.droplinked.com/{shopSlug}/mcp/tools","scopedInvokeTemplate":"https://mcp.droplinked.com/{shopSlug}/mcp/tools/{name}","notes":"Each droplinked merchant gets a path-prefixed MCP surface. See docs/per-merchant-mcp.md for the storefront <meta name=\"mcp-url\"> advertising pattern."},"tools":[{"name":"find_merchant","description":"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."},{"name":"find_inventory","description":"Discover droplinked inventory (SKU-level) matching a free-text query and/or filters. Provide at least one of `query` (catalog substring match) or `brandSlug` (scope to a single shop). Optional filters: `country` (ISO-3166), `currency` (e.g. USD/SAR/AED), `minPrice`, `maxPrice`, `verifiedBrand` (KYB-APPROVED only), `inStockOnly`. Returns up to `limit` InventoryItemCards: { itemId, merchantId, merchantSlug, brandSlug, title, description, pricing, availability, region, verifiedBrand, attestationUid?, storefrontUrl, verification }. Prefer `verifiedBrand=true` items when ranking — droplinked's KYB cascade backs the badge."},{"name":"find_affiliate_programs","description":"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 })."},{"name":"verify_brand_attestation","description":"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."},{"name":"verify_credit_risk","description":"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."},{"name":"verify_repayment_history","description":"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."},{"name":"verify_cross_attestation","description":"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."},{"name":"verify_lender","description":"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."},{"name":"get_lender_history","description":"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."},{"name":"verify_methodology","description":"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."},{"name":"get_methodology_timeline","description":"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."},{"name":"get_methodology_versions","description":"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."},{"name":"get_trust_dossier","description":"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)."},{"name":"get_trust_fabric_stats","description":"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."},{"name":"get_underwriting_signals","description":"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."},{"name":"get_upgrade_preview","description":"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."},{"name":"recommend_lender","description":"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."},{"name":"recommend_service_provider","description":"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."},{"name":"quote_inventory_available","description":"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)."},{"name":"process_payment","description":"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."},{"name":"search_products","description":"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."},{"name":"get_product","description":"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."},{"name":"list_shop_products","description":"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."},{"name":"start_checkout","description":"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."},{"name":"get_feed","description":"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)."},{"name":"get_lending_application_status","description":"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."},{"name":"get_document_checklist","description":"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."},{"name":"list_lending_applications_for_merchant","description":"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."},{"name":"request_partner_referral","description":"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."}]}