io.github.themewireco/synchronity MCP Server

Synchronity is commerce infrastructure for AI assistants that connects to a hosted Synchronity gateway at https://api.synchronity.app. It provides an MCP server (“packages/mcp”) exposing shopping tools to search, compare products, and support cart and checkout flows requiring buyer approval.

🛠️ Key Features

MCP server included in packages/mcp
Exposes shopping tools for:
- Search
- Compare
- Cart
- Checkout
Checkout requires buyer approval
Uses hosted gateway at https://api.synchronity.app (nothing to self-host)

🚀 Use Cases

Shop across connected e-commerce stores via an AI assistant
Assist buyers with product discovery (search and compare)
Drive purchase steps (cart and checkout) with explicit buyer approval

⚡ Developer Benefits

Public repository includes the MCP server components
MIT-licensed public pieces available
Clear integration point via the Synchronity gateway URL

⚠️ Limitations

No self-hosting; relies on the hosted Synchronity gateway (https://api.synchronity.app).

Synchronity

Shop anything online with AI — search, compare, and buy across connected stores from any AI assistant.

Synchronity is commerce infrastructure for AI assistants. It connects to the hosted Synchronity gateway at https://api.synchronity.app — there is nothing to self-host.

This repository contains the public, MIT-licensed pieces:

Part	What it is
`packages/mcp`	The MCP server — exposes shopping tools to Claude, Cursor, and any MCP client
`packages/sdk`	Typed gateway client used by the MCP server
`desktop-extension`	Claude Desktop extension (`.mcpb`) source — a zero-dependency bridge to the gateway
`plugins/synchronity`	Cross-assistant plugin (Claude Code + Codex) — install via the marketplace below
`woocommerce`	The Synchronity WooCommerce plugin — makes a store agent-ready

Releases attach prebuilt artifacts: the synchronity.mcpb desktop extension and the WooCommerce plugin zip. See Releases.

For shoppers — connect your AI assistant

Claude Desktop (easiest)

Download synchronity.mcpb from the latest release (or from api.synchronity.app/setup/download).
Open it with Claude Desktop and click Install.
Ask Claude to shop — e.g. "Search Synchronity for a wireless keyboard."

Claude Code (plugin marketplace)

bash

/plugin marketplace add themewireco/synchronity
/plugin install synchronity@synchronity

Then just shop — "find me a birthday cake from my stores". The plugin bundles the synchronity-commerce skill and runs the MCP server locally via npx, so there is nothing to clone or build.

Codex

Add the Synchronity plugin from this repo (plugins/synchronity). Codex reads .codex-plugin/plugin.json and connects to the hosted MCP at https://api.synchronity.app/mcp, with the same synchronity-commerce skill.

Any MCP client (manual)

bash

npm install && npm run build

jsonc

{
  "mcpServers": {
    "synchronity": {
      "command": "node",
      "args": ["/absolute/path/to/synchronity/packages/mcp/dist/index.js"],
      "env": { "GATEWAY_URL": "https://api.synchronity.app" }
    }
  }
}

GATEWAY_URL defaults to https://api.synchronity.app. Sensitive actions (checkout, payment) require buyer approval — the assistant walks you through a one-time approval step.

What the assistant can do

Product search & details (with inline images), compare across stores, reviews, cart management, shipping, checkout, card/mobile-money payment, order tracking, and human-in-the-loop approval for sensitive actions.

For merchants — make your WooCommerce store agent-ready

Download the WooCommerce plugin zip from the latest release.
In WordPress: Plugins → Add New → Upload Plugin, choose the zip, Install and Activate.
Open WooCommerce → Synchronity, copy your connector key, and register your store with Synchronity.

Your store keeps its own catalog, currency, shipping, and orders — Synchronity routes agent requests to it through the gateway.

Build the artifacts yourself

bash

npm run build         # build the MCP server + client
npm run build:mcpb    # -> synchronity.mcpb (Claude Desktop extension)
npm run build:plugin  # -> synchronity-woocommerce-v<version>.zip

Configuration

Env var	Default	Purpose
`GATEWAY_URL`	`https://api.synchronity.app`	Synchronity gateway base URL
`DEFAULT_SITE_ID`	—	Optional default store to scope tools to
`DEBUG`	`false`	Verbose logging to stderr

Reviewing & testing

New here or reviewing the connector? Follow the end-to-end walkthrough: docs/reviewer-testing.md.

Privacy & support

Privacy Policy: PRIVACY.md · at synchronity.app/privacy-policy
Support: hello@themewire.co

site_id	string	required	Registered site ID (e.g., "site_abc123" or "shopify_store_1")
query	string	optional	Optional single search term (product name/keyword). OMIT to browse; for several names use `queries`.
queries	array	optional	Search several product names at once (e.g. when the buyer lists multiple items). Returns all matches in ONE call/card instead of searching one at a time. Use `query` for a single search, `queries` for several, or omit both to browse.
category	string	optional	Filter by product category (optional)
min_price	string	optional	Minimum price filter in store currency, format: "19.99" (optional)
max_price	string	optional	Maximum price filter in store currency, format: "199.99" (optional)
in_stock	boolean	optional	Filter to in-stock items only (default: false)
page	integer	optional	Page number (1-indexed, default: 1)
per_page	integer	optional	Results per page (default: 20, max: 100)

site_id	string	required	Registered site ID
product_id	string	required	Product ID from the site (platform-specific format)

site_id	string	required	Registered site ID
product_id	string	required	Product ID
limit	integer	optional	Max reviews to return (default: 10)
page	integer	optional	Page number (default: 1)

site_id	string	required	Registered site ID
product_id	string	required	Product ID to watch
variant_id	string	optional	Specific variant to watch (optional)
email	string	optional	Buyer's email for the restock alert (recommended — without it no alert is sent)
product_title	string	optional	Product name, for a clearer alert + merchant view (optional)

site_ids	array	required	List of registered site IDs to compare across
query	string	required	Search query for product comparison
category	string	optional	Filter by category (optional)
min_price	string	optional	Minimum price filter (optional)
max_price	string	optional	Maximum price filter (optional)
in_stock	boolean	optional	Filter to in-stock items only (optional)

items	array	required	Products to buy. Each entry: { site_id, product_id, quantity, variant_id?, addons? }. Items may span multiple stores (grouped by site_id).
shipping_address	object	required	Buyer delivery address (applied to every store).
customer	object	optional	Optional buyer contact carried for checkout; customer.email arms back-in-stock alerts for out-of-stock items.

site_id	string	required	Registered site ID
currency	string	optional	ISO 4217 currency code (e.g., "USD", "EUR", "GBP"). Defaults to site currency.

site_id	string	required	Registered site ID
cart_id	string	required	Cart ID
country_code	string	required	ISO-3166 alpha-2 country code (e.g. US)
postal_code	string	optional	Postal/ZIP code for accurate rates
state	string	optional	State/province/region code where carriers need it
city	string	optional	City

site_id	string	required	Registered site ID
cart_id	string	required	Cart ID to checkout
buyer_delegation_token	string	required	Delegation token from buyer (OAuth-like flow)
customer_name	string	required	Full name of the customer placing the order
customer_email	string	required	Email address of the customer placing the order
customer_phone	string	required	Customer contact / billing phone number (E.164 preferred, e.g. +233201234567)
shipping_name	string	required	Recipient full name
shipping_line1	string	required	Shipping address line 1 (street)
shipping_line2	string	optional	Shipping address line 2 (apt/suite) [optional]
shipping_city	string	required	Shipping city
shipping_state	string	required	Shipping state or province
shipping_postal_code	string	required	Shipping postal code
shipping_country	string	required	ISO 3166-1 alpha-2 country code (e.g., "US", "GB")
shipping_phone	string	optional	Recipient phone for the shipping address (E.164 preferred); defaults to customer_phone if omitted
notes	string	optional	Optional order notes

site_id	string	required	Registered site ID
order_id	string	required	Order ID
buyer_delegation_token	string	optional	The buyer's delegation token (from their checkout approval); required to read their order.

io.github.themewireco/synchronity MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

list_sites

search_products

get_product

get_product_reviews

request_back_in_stock

compare_products

create_cart

add_to_cart

quick_checkout

remove_from_cart

set_cart_quantity

apply_coupon

get_cart

get_active_cart

set_shipping_address

select_shipping_option

execute_checkout

get_order

list_orders

request_delegation

submit_delegation_otp

check_delegation

get_payment_methods

initiate_payment

submit_payment_otp

get_payment_status

Synchronity

For shoppers — connect your AI assistant

Claude Desktop (easiest)

Claude Code (plugin marketplace)

Codex

Any MCP client (manual)

What the assistant can do

For merchants — make your WooCommerce store agent-ready

Build the artifacts yourself

Configuration

Reviewing & testing

Privacy & support

License

Install

Configuration