E-commerce Integration Guide

This guide is for developers of an e-commerce platform who want to let their users place orders, look up orders, track logistics, and request refunds directly inside the Webnav.ai chat assistant.

Webnav.ai is an orchestration layer: it understands the user, extracts parameters, and calls your tools. You keep full control of business logic, data, and money. Webnav.ai never stores your orders or customers.

• Integration model: Webnav.ai connects to your MCP (Model Context Protocol) tool server over JSON-RPC 2.0 over HTTP. It is the MCP client; you are the MCP server.
• You implement: one HTTP endpoint that speaks initialize, tools/list, and tools/call.
• You configure: your MCP endpoint (and optional auth headers) in Dashboard → AI Actions.

This page is a high-level overview. For the full wire protocol, tool field specs, and dashboard steps, see the MCP Integration Guide. For an onboarding checklist and what to hand back to Webnav.ai, see MCP Provider Onboarding.

---

Architecture

┌─────────┐   ask     ┌───────────────┐  JSON-RPC 2.0   ┌──────────────┐
│ Visitor │ ────────► │  Webnav.ai    │ ──────────────► │ Your MCP     │
│ (widget)│ ◄──────── │  (MCP client) │ ◄────────────── │ server       │
└─────────┘  reply     └───────────────┘   tool result    └──────────────┘

1. Visitor sends a message.
2. Webnav.ai discovers your tools (tools/list), picks one, and extracts its arguments.
3. It calls the tool via tools/call against your MCP endpoint.
4. Your server runs the operation and returns a result.
5. The LLM turns the result into a natural reply (and an optional UI card).

Write tools (create_order, create_refund) add a confirmation step before step 3 — the visitor must click Confirm before anything executes.

---

The five canonical e-commerce tools

These are the tools Webnav.ai understands natively. Implement all five for full coverage, or a subset.

Tool	Type	Confirmation	Purpose
list_products	read	no	Return product catalogue (used for SKU validation)
query_order	read	no	Look up an order's status / details
query_logistics	read	no	Track a shipment
create_order	write	yes	Place a new order — all items in one items[] call
create_refund	write	yes	Start a refund request

list_products is used internally to validate SKUs before showing a write confirmation card: if the visitor's requested SKU is not in your catalogue, the assistant asks them to pick a real product instead of presenting a confirmation card for an invalid SKU.

create_order takes a multi-item items[] array, so a visitor can buy several products in one conversation turn — Webnav.ai calls create_order once with all items and shows a single confirmation card.

Response shape — return the canonical { ok, data, display } (richer widget cards) or the standard MCP { content, isError } block. Business errors use { ok: false, error_code, message } with descriptive codes (ORDER_NOT_FOUND, OUT_OF_STOCK, SKU_NOT_FOUND). Full field specs and JSON examples are in the MCP Integration Guide → Tool specifications.

---

Confirmation flow (write tools)

LLM collects args → Webnav.ai creates a pending action → widget shows Confirm / Cancel
   → visitor clicks Confirm → Webnav.ai calls the tool exactly once → result card

Webnav.ai decides a tool is a write operation by OR-ing three signals — a write tool is never accidentally skipped:

1. annotations.destructiveHint: true from your tools/list response, or
2. the tool name matches create_*, refund_*, cancel_*, or pay_*, or
3. the tool is in the merchant's Confirm tools list configured in the dashboard.

Read tools (readOnlyHint: true) are called directly with no card.

The pending action is single-use and time-limited, bound to the visitor — it cannot be replayed or confirmed by anyone else. Still, make write tools idempotent (use an idempotency key) so a network retry never creates a second order or refund.

---

Security

Requirement	Why
Serve over HTTPS on a public host	Webnav.ai pins the resolved IP and refuses private/loopback/metadata addresses (SSRF protection).
Validate auth headers	Pass a bearer token or API key via auth headers and validate it on every request.
Make write tools idempotent	Webnav.ai sends a single confirmed call, but network retries can happen.
list_products returns your real catalogue	Every SKU is validated against it before a confirmation card is shown.

In MCP mode the Dashboard Test Connection probe is always proxied through the Webnav.ai backend — your endpoint is never contacted directly from the browser.

---

Next steps

• MCP Integration Guide — full wire protocol (initialize / tools/list / tools/call), per-tool field specs, annotations, error normalization, dashboard config, and demo MCP servers.
• MCP Provider Onboarding — onboarding checklist, hard requirements, and the go-live acceptance checklist.
• AI Actions — the merchant-facing overview of how actions, confirmation, and call logs work.