MCP Server - Droplinked Developers

Droplinked exposes its commerce primitives — catalog and merchant discovery, cart composition, checkout, refunds, and trust-fabric reads — as Model Context Protocol tools. The canonical surface is the standalone droplinked-mcp connector at https://mcp.droplinked.com — the host submitted to the Anthropic Connectors Directory and listed in the HOL registry via the droplinked/droplinked-codex-plugin bundle. Any MCP-capable agent discovers the surface from a public well-known doc and calls it over streamable HTTP.

There are two MCP surfaces. mcp.droplinked.com (this page) is the canonical connector — it’s what you add to Claude, ChatGPT, or Cursor. The Droplinked backend also serves an always-on backend MCP surface at apiv3.droplinked.com/mcp/v1 — see Alternate surface below. Prefer the connector.

For the full, code-grounded tool roster see Inventory MCP.

Discovery

Start at the well-known discovery doc. It’s public (no key), cacheable, and lists every tool with its JSON-schema input shape:

curl -s https://mcp.droplinked.com/.well-known/mcp.json | jq

{
  "name": "droplinked-mcp",
  "version": "1.0.0",
  "protocolVersion": "2024-11-05",
  "transport": "streamable-http",
  "endpoints": {
    "mcp": "/mcp",
    "toolsList": "/mcp/tools",
    "toolsCall": "/mcp/tools/{name}"
  },
  "capabilities": {
    "tools": { "listChanged": false },
    "resources": { "listChanged": false, "subscribe": false },
    "prompts": false
  },
  "tools": [ { "name": "search_products", "description": "…" }, … ]
}

A per-merchant variant scopes the surface to one shop’s catalog. Each shop advertises a manifest and a pre-scoped tool list:

# Per-merchant manifest (public)
curl -s https://mcp.droplinked.com/{shopSlug}/manifest | jq

# Per-merchant tool list, pre-bound to this shop
curl -s https://mcp.droplinked.com/{shopSlug}/mcp/tools

Health is at GET /healthz. See Consume Droplinked MCP for the full per-merchant pinning flow.

Transport

The connector speaks streamable HTTP at protocolVersion 2024-11-05. There’s one JSON-RPC endpoint plus a REST-style shim for clients that prefer plain HTTP calls:

Method + path	Purpose	Auth
`POST /mcp`	The MCP lifecycle over JSON-RPC 2.0 on one endpoint — `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`.	Read tools open; write `tools/call` needs `X-MCP-API-Key`.
`GET /mcp/tools`	REST shim — list available tools (`{ tools: [...] }`).	Public, no key.
`POST /mcp/tools/{name}`	REST shim — invoke a tool by name with a flat `{ arguments }` body.	Read tools open; write tools need `X-MCP-API-Key`.
`GET /.well-known/mcp.json`	Discovery doc.	Public, no key.
`GET /healthz`	Liveness probe.	Public, no key.

The JSON-RPC endpoint accepts the standard envelope; the REST shim carries the tool name in the path and the arguments in a flat body. Errors use the MCP/JSON-RPC codes (-32601 unknown tool/method, -32602 invalid arguments). A tool whose logic fails (e.g. shop not found) still returns 200 with isError: true so the agent can recover.

# List tools — public, no key
curl -s https://mcp.droplinked.com/mcp/tools | jq

# Call a read-only tool — public, no key
curl -s -X POST https://mcp.droplinked.com/mcp/tools/search_products \
  -H 'content-type: application/json' \
  -d '{ "query": "wool beanie" }'

curl -s -X POST https://mcp.droplinked.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "search_products", "arguments": { "query": "wool beanie" } }
  }'

Authentication — two tiers (live)

The connector runs a two-tier auth model, live in production as of 2026-08-05. It is not a “later phase” and it is not fully open.

Read-only tools are public — no key

Every discovery, catalog, trust, verify, and recommend tool is callable with no credential. GET /mcp/tools and the read side of tools/call are open, so Anthropic, ChatGPT, Cursor, and any MCP client can list and call them with zero setup: find_merchant · find_inventory · search_products · get_product · list_shop_products · verify_brand_attestation · get_trust_dossier · recommend_lender — and the rest of the read-only catalog/trust surface.

Write tools require `X-MCP-API-Key`

State-changing tools return 401 without a key and require the X-MCP-API-Key header: process_payment · start_checkout · cart.addLine · cart.updateLineQuantity · cart.removeLine · cart.applyDiscount · quote_inventory_available · request_partner_referral · quote_credit_terms · report_repayment · request_brand_attestation. Request a key from ops@droplinked.com. Treat it like an API secret — it identifies your agent for attribution, rate-limiting, and the commission rail.

# Write tool — 401 without the key
curl -s -X POST https://mcp.droplinked.com/mcp/tools/start_checkout \
  -H 'content-type: application/json' \
  -H "X-MCP-API-Key: $DROPLINKED_MCP_KEY" \
  -d '{ "shopUrl": "warmwool", "items": [{ "skuId": "65f…", "quantity": 1 }] }'

Two-header identity model

X-MCP-API-Key authorizes the write request to the server — it is what lifts the 401 on write tools.
Authorization: Bearer <agent-jwt> (optional) carries the consumer agent’s identity for tools that require an authenticated caller.

Send both when a write tool needs the calling agent’s identity; send just X-MCP-API-Key for writes that don’t. Rate-limiting applies to all routes, keyed or not.

Registry + one-click add

The connector is packaged for one-click add through the droplinked/droplinked-codex-plugin bundle — the HOL registry listing. Agents (and the Anthropic Connectors Directory) can pull the plugin to register mcp.droplinked.com without hand-wiring the transport.

Connect from an agent

Claude / Claude Code

Point Claude’s remote connector at the single streamable-HTTP endpoint. The client drives the initialize handshake and negotiates protocolVersion 2024-11-05 automatically:

claude mcp add --transport http droplinked https://mcp.droplinked.com/mcp

The client lists tools via tools/list and dispatches calls via tools/call. Read-only tools work with no key. To call write tools (checkout, payments, cart mutations), add your X-MCP-API-Key as a header on the connector.

ChatGPT / OpenAI Agents SDK

Add https://mcp.droplinked.com/mcp as an MCP tool source, or ingest the ACP feed for product discovery. The read-only tool surface and the ACP feed are both public.

Any MCP client (manual)

GET /.well-known/mcp.json to learn the tool surface (public).
GET /mcp/tools — or POST /mcp with tools/list — to enumerate tools + input schemas (public).
Invoke: POST /mcp/tools/{name} with { arguments }, or POST /mcp with a tools/call envelope. Read tools need no key; write tools need X-MCP-API-Key.

How it fits together

   AI agent (Claude / ChatGPT / Cursor / Agents SDK)
              │  GET  /.well-known/mcp.json   (discover — public)
              │  GET  /mcp/tools              (list — public, no key)
              │  POST /mcp                    (JSON-RPC: initialize / tools/list / tools/call)
              │  POST /mcp/tools/{name}       (REST call — writes need X-MCP-API-Key)
              ▼
   droplinked-mcp connector (mcp.droplinked.com)  ·  two-tier auth
              │  read-only tools open · write tools keyed (401 without X-MCP-API-Key)
              ▼
   Droplinked backend (apiv3) — McpToolRegistryService
              │  catalog / cart / order / trust-fabric reads + writes
              ▼
   PSP resolver (Stripe · PayPal · Paymob · MamoPay · x402 · …)  ·  EAS trust fabric
              ▼
   recordAgenticIntent → attribution ledger → 70 / 20 / 10 settlement

Alternate surface: apiv3 backend MCP

The Droplinked backend serves an always-on backend MCP surface directly at apiv3.droplinked.com/mcp/v1, over four JSON-RPC routes. It’s the embedded surface the connector proxies to — useful if you’re integrating against the backend host directly rather than through the canonical connector.

Method + path	Purpose
`POST /mcp/v1/tools/list`	List available tools (`{ tools: [...] }`).
`POST /mcp/v1/tools/call`	Invoke a tool by name.
`POST /mcp/v1/resources/list`	List MCP resources.
`POST /mcp/v1/resources/read`	Read a resource by `mcp://droplinked/...` URI.

Each route accepts both request shapes — a flat body ({ "name": "searchProducts", "arguments": { … } }) or a JSON-RPC 2.0 envelope ({ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { … } }) — and mirrors the shape back in the response.

curl -s -X POST https://apiv3.droplinked.com/mcp/v1/tools/call \
  -H 'content-type: application/json' \
  -d '{ "name": "searchProducts", "arguments": { "query": "wool beanie" } }'

Discovery for this surface is at GET https://apiv3.droplinked.com/.well-known/mcp.json.
Write-tool gating on this surface is being aligned to the connector’s two-tier model — treat write tools here as gated, and use the canonical connector’s X-MCP-API-Key model as the reference behavior.
Admin diagnostics (queryEventLog, traceAttestationLineage, getInventoryDrift) are gated by an _adminKey argument matching MCP_ADMIN_SECRET — not a header. This is scoped to the backend surface’s diagnostic tools only.

New integrations should target mcp.droplinked.com. The apiv3 surface stays in place as a backend-embedded MCP, but the canonical connector is the discovery-directory listing and the one that carries the live two-tier auth model.

Inventory MCP

The full tool registry, read/write annotations, and findInventory details.

Consume the MCP

Build an agentic shopping loop end-to-end against mcp.droplinked.com.

ACP Feed

The Stripe Agentic Commerce Protocol product feed for shopping-surface ingestion.

Attribution + Commission

How agentic conversions settle 70 / 20 / 10.

​Discovery

​Transport

​Authentication — two tiers (live)

​Read-only tools are public — no key

​Write tools require X-MCP-API-Key

​Two-header identity model

​Registry + one-click add

​Connect from an agent

​Claude / Claude Code

​ChatGPT / OpenAI Agents SDK

​Any MCP client (manual)

​How it fits together

​Alternate surface: apiv3 backend MCP

​Related

Inventory MCP

Consume the MCP

ACP Feed

Attribution + Commission

Discovery

Transport

Authentication — two tiers (live)

Read-only tools are public — no key

Write tools require `X-MCP-API-Key`

Two-header identity model

Registry + one-click add

Connect from an agent

Claude / Claude Code

ChatGPT / OpenAI Agents SDK

Any MCP client (manual)

How it fits together

Alternate surface: apiv3 backend MCP

Related