MCP Server - Droplinked Developers

Droplinked exposes its commerce primitives — catalog search, cart composition, order placement, refunds, and trust-fabric reads — as Model Context Protocol tools, served directly by the Droplinked backend at apiv3.droplinked.com. Any MCP-capable agent can discover the surface from a well-known doc and call it over HTTP. For the full, code-grounded tool roster see Inventory MCP.

Discovery

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

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

{
  "name": "droplinked-mcp-server",
  "version": "0.1.0",
  "protocolVersion": "2024-11-05",
  "transport": "http",
  "endpoints": {
    "toolsList": "/mcp/v1/tools/list",
    "toolsCall": "/mcp/v1/tools/call",
    "resourcesList": "/mcp/v1/resources/list",
    "resourcesRead": "/mcp/v1/resources/read"
  },
  "capabilities": {
    "tools": { "listChanged": false },
    "resources": { "listChanged": false, "subscribe": false },
    "prompts": false
  },
  "tools": [ { "name": "searchProducts", "description": "…" }, … ]
}

A per-shop variant scopes the surface to one merchant’s catalog (it advertises only the shop-scoped read tools: searchProducts, getProductDetail, getShopInfo, getStockoutAlerts):

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

Transport

The server speaks MCP over HTTP on four JSON-RPC routes. Every route is public (the current phase is unauthenticated; admin diagnostics are gated by an _adminKey argument, not a header).

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:

Flat body — { "name": "searchProducts", "arguments": { … } }
JSON-RPC 2.0 envelope — { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "searchProducts", "arguments": { … } } }

The response mirrors the request: a flat body gets a flat result; a JSON-RPC envelope gets { "jsonrpc": "2.0", "id", "result" }. 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.

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

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

Planned: Streamable HTTP

A single-endpoint Streamable HTTP transport — the modern MCP transport every current official client (including the Claude remote connector) prefers — is implemented and gated behind MCP_STREAMABLE_HTTP_ENABLED.

Streamable HTTP is preview — it is feature-flagged off until the flag is enabled in production. Until then, use the /mcp/v1/* JSON-RPC routes above, which every current MCP client already supports. The legacy /mcp/v1/* routes stay in place when Streamable HTTP lands — nothing is removed.

When enabled, it adds three routes at a single path:

Method + path	Purpose
`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`.
`GET /mcp`	Server→client SSE stream (with keep-alive heartbeat) for server-initiated messages.
`OPTIONS /mcp`	CORS preflight.

initialize handshake — the client opens with an initialize request; the server replies with its capabilities and mints an Mcp-Session-Id. The client echoes that header on every subsequent call, and the server accepts it to bind the session.
Protocol-version negotiation — the server supports 2025-06-18, 2025-03-26, and 2024-11-05, and negotiates the highest version the client offers.
Tool annotations — the tools/list response over this transport includes the read-only / destructive hints described in Inventory MCP → Tool annotations.

# Preview only — works once MCP_STREAMABLE_HTTP_ENABLED is on.
curl -s -X POST https://apiv3.droplinked.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "0.1.0" }
    }
  }' -i | grep -i mcp-session-id

Connect from an agent

Claude / Claude Code

MCP clients connect to the HTTP transport. Point your client at the discovery doc, or call the JSON-RPC routes directly:

claude mcp add --transport http droplinked https://apiv3.droplinked.com/mcp/v1/tools/call

The client lists tools via tools/list and dispatches calls via tools/call. No API key is required in the current phase. Once the Streamable HTTP transport above is enabled, you point Claude’s remote connector at the single POST /mcp endpoint instead, and the client drives the initialize handshake automatically.

ChatGPT / OpenAI Agents SDK

Add the JSON-RPC tools/call endpoint as an HTTP tool source, or ingest the ACP feed for product discovery. Both surfaces are public.

Any MCP client (manual)

GET /.well-known/mcp.json to learn the tool surface.
POST /mcp/v1/tools/list to enumerate tools + input schemas.
POST /mcp/v1/tools/call with { name, arguments } (or the JSON-RPC envelope) to invoke.

How it fits together

   AI agent (Claude / ChatGPT / Cursor / Agents SDK)
              │  GET /.well-known/mcp.json   (discover)
              │  POST /mcp/v1/tools/call     (invoke, flat or JSON-RPC)
              ▼
   Droplinked backend (apiv3) — McpToolRegistryService
              │  catalog / cart / order / trust-fabric reads + writes
              ▼
   PSP resolver (Stripe · PayPal · Telr · Bonum · PayMob · x402)  ·  EAS trust fabric
              ▼
   recordAgenticIntent → attribution ledger → 70 / 20 / 10 settlement

Notes on the current phase

Public, unauthenticated. Every tool route is public today. Admin diagnostics (queryEventLog, traceAttestationLineage, getInventoryDrift) require an _adminKey argument matching MCP_ADMIN_SECRET. Per-merchant API-key auth and write-tool guards are a later phase.
CORS is open (*) on the tool routes — they’re read-mostly and carry no cookies — and each route answers a sibling OPTIONS preflight.
The discovery doc is the contract. It’s regenerated on deploy when the tool surface changes and cached for one hour.

Inventory MCP

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

ACP Feed

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

Consume the MCP

Build an agentic shopping loop end-to-end.

Attribution + Commission

How agentic conversions settle 70 / 20 / 10.

​Discovery

​Transport

​Planned: Streamable HTTP

​Connect from an agent

​Claude / Claude Code

​ChatGPT / OpenAI Agents SDK

​Any MCP client (manual)

​How it fits together

​Notes on the current phase

​Related

Inventory MCP

ACP Feed

Consume the MCP

Attribution + Commission

Discovery

Transport

Planned: Streamable HTTP

Connect from an agent

Claude / Claude Code

ChatGPT / OpenAI Agents SDK

Any MCP client (manual)

How it fits together

Notes on the current phase

Related