MCP Provider Onboarding

This page is the handoff kit for a third-party e-commerce or business platform that wants to connect to Webnav.ai over the Model Context Protocol (MCP). It lists exactly what Webnav.ai gives you, what you must deliver, the decisions you need to make, and the go-live acceptance checklist.

For the full wire protocol and field-by-field tool specs, see the MCP Integration Guide. This page is the onboarding overview; that page is the reference.

MCP mode is an Enterprise feature.

---

How it works (one diagram)

Visitor → Widget → Webnav.ai ──JSON-RPC 2.0 over HTTPS──► Your MCP Server
                              ◄──────────────────────────  (tool result)

You expose one HTTP endpoint that speaks JSON-RPC 2.0. Webnav.ai is the MCP client; you are the MCP server. Webnav calls three methods only: initialize, tools/list, tools/call. You never call us.

---

1. What Webnav.ai provides to you

Item	Detail
Protocol spec	The MCP Integration Guide — handshake, tool discovery, tool-call wire format, error codes.
Canonical tool contracts	5 standard tools Webnav understands natively (below). Implement all or a subset.
Reference implementations	examples/mcp_server.py (standalone, port 4100) and the demo shop's integrated /mcp (examples/shop/shop_server.py, port 4000) — copy-paste starting points.
Test Connection tool	Dashboard → AI Actions → MCP → Test Connection. We probe your endpoint (initialize + tools/list) through our backend and show the discovered tools + annotations. Your endpoint is never contacted directly from the browser.
SSRF-safe proxy	All calls to your endpoint go through our backend, which pins the resolved IP and refuses private/loopback/metadata addresses.
Confirmation flow	Write tools get a visitor-facing confirmation card before execution — handled entirely by Webnav, no work on your side.
Call logs	Dashboard → AI Actions → Call Logs records every tool call (name, redacted args, status, latency, error).
Error normalization	Transport/protocol failures are mapped to stable MCP_* codes (see guide).

---

2. What you must deliver to Webnav.ai

To complete onboarding, hand back these four things:

1. MCP endpoint URL — a single HTTPS URL, e.g. https://mcp.yourshop.com/mcp.
2. Tool list — which of the canonical tools you implement (and any custom ones).
3. Auth headers (if any) — the header name(s) and how to obtain a token. Webnav stores these per-domain and forwards them on every request.
4. Sandbox/test access — a test environment + sample data (products, a test order id) so we can run Test Connection and an end-to-end order before go-live.

Hard requirements

Requirement	Why
HTTPS, public host	We pin the resolved IP and refuse private/loopback addresses (SSRF protection). http://localhost works only in local dev with ACTIONS_ALLOW_INSECURE=true.
initialize returns a supported protocolVersion	Use 2024-11-05 (also accepted: 2025-03-26, 2025-06-18). Other values still work but raise a versionMismatch warning.
inputSchema is a JSON Schema object ("type": "object")	Otherwise we reset it to an empty schema and the model loses your parameters.
Write tools are idempotent	We send a single confirmed call, but network retries can happen. Design create_order / create_refund to be safe if received twice (use an idempotency key).
list_products returns your real catalogue	We validate every SKU against it before showing a confirmation card. Unknown SKUs are rejected, not ordered.
Write tools are marked	Set annotations.destructiveHint: true on order/refund/cancel/pay tools (see confirmation model below).

---

3. Canonical tools (the contract)

Tool	Type	Confirmation	Purpose
list_products	read	no	Return catalogue for SKU validation + product cards
query_order	read	no	Order status / details by order_id
query_logistics	read	no	Shipment tracking by order_id
create_order	write	yes	Place an order — all items in one items[] call
create_refund	write	yes	Start a refund by order_id

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: MCP Integration Guide → Tool specifications.

Confirmation model (important)

Webnav decides whether to show a confirmation card by OR-ing three signals — a write tool is never accidentally skipped:

1. annotations.destructiveHint: true (self-reported by you), or
2. tool name matches create_* / refund_* / cancel_* / pay_*, or
3. the tool is in the merchant's Confirm tools list configured in the dashboard.

So even if you forget the annotation, a create_order still confirms. Conversely, read tools (readOnlyHint: true) are called directly with no card.

---

4. Integration question checklist

Decisions you (the integrator) must settle before/while building. Tick each one off.

Endpoint & protocol

• [ ] Endpoint URL + path (single JSON-RPC HTTP endpoint).
• [ ] protocolVersion returned by initialize (recommend 2024-11-05).
• [ ] serverInfo.name / version.

Tools & schema

• [ ] Which canonical tools (all 5, or a subset)?
• [ ] Every inputSchema is type: "object".
• [ ] create_order accepts a multi-item items[] array (one call, one card).

Confirmation & annotations

• [ ] Write tools carry destructiveHint: true; read tools readOnlyHint: true.
• [ ] title set for a friendly confirmation-card label.

Response & errors

• [ ] Canonical {ok,data,display} or MCP content block — pick one.
• [ ] Business error codes defined (ORDER_NOT_FOUND, OUT_OF_STOCK, …).

Auth & security

• [ ] Auth header(s) — do you validate a bearer token / API key on every request?
• [ ] Do you need visitor identity (e.g. "my orders")? If so, how is the user token passed/validated?
• [ ] Write tools idempotent (idempotency key strategy)?
• [ ] HTTPS + public host confirmed.

Multi-tenant & data

• [ ] If one endpoint serves multiple Webnav domains/merchants, how do you isolate them (per-tenant token in headers)?
• [ ] Read tools (query_order etc.) hit your real order data, not a mock store.

---

5. Integration steps

1. Build the endpoint. Implement POST /mcp dispatching initialize / tools/list / tools/call. Wrap your existing order/catalogue logic — see examples/shop/shop_server.py for a working pattern whose /mcp endpoint shares the storefront's order store.
2. Self-test the wire protocol with curl (handshake / discover / call) — see guide.
3. Deploy behind HTTPS on a public host. Add auth-header validation if used.
4. Configure in the dashboard: AI Actions → Mode = MCP → enter your endpoint → add Auth Headers → Save, then Test Connection (must list your tools). Mark write tools under Confirm tools.
5. End-to-end test in the live widget: ask the assistant to browse, order (confirm card → place), track, and refund. Verify orders land in your real system.

Order of operations matters: Save first, then Test Connection — the probe reads the saved endpoint, not the value still in the input box.

---

6. Go-live acceptance checklist

• [ ] Test Connection lists all expected tools with correct annotations, no versionMismatch.
• [ ] list_products returns the live catalogue; invalid SKUs are rejected before any order.
• [ ] create_order with multiple items produces one confirmation card and one order.
• [ ] query_order / query_logistics reflect real system state.
• [ ] create_refund is idempotent and reflects in your system.
• [ ] Auth headers validated; unauthenticated calls rejected.
• [ ] Endpoint is HTTPS on a public host; private addresses refused.
• [ ] Call Logs show successful calls with sane latency.

Once all boxes are ticked, the integration is production-ready.