MCP Server
The 26 commerce tools Synchronity exposes to Claude, ChatGPT, Cursor, and any other Model Context Protocol client.
What is MCP?
The Model Context Protocol is Anthropic's open standard for letting LLMs call tools running on the user's machine (or hosted elsewhere). Synchronity ships an MCP server that exposes the gateway's REST API as 26 typed tools, so an agent can call search_products the same way it'd call read_file.
Two delivery modes
The same MCP server ships two ways:
- stdio binary — runs locally; your client spawns it and communicates over stdin/stdout. Used by Claude Desktop and Cursor's local MCP config. Installed via the
.mcpbbundle ornpx @synchronity/mcp-server. - Hosted HTTP — the gateway mounts the same tools at its root. Remote agents (ChatGPT custom connectors, hosted Claude.ai) connect to
https://api.synchronity.app/mcpwithout installing anything.
The 26 tools
| Category | Tool | What it does |
|---|---|---|
| Discovery | list_sites | Returns all sites the agent has access to. |
| Discovery | search_products | Cross-store keyword search, returns ranked AMPS payload. |
| Discovery | get_product | Fetch one product by ID + site. |
| Discovery | get_product_reviews | Reviews for a product. |
| Discovery | compare_products | Side-by-side comparison across stores. |
| Discovery | request_back_in_stock | Subscribe the buyer to a back-in-stock email alert for an out-of-stock product. |
| Cart | create_cart | Open a new cart on a site. |
| Cart | add_to_cart | Add a product variant + quantity. |
| Cart | set_cart_quantity | Set a line's quantity (0 removes it). |
| Cart | remove_from_cart | Remove a line item. |
| Cart | get_cart | Fetch current cart state. |
| Cart | get_active_cart | Resume the buyer's in-progress cart. |
| Cart | apply_coupon | Apply a discount code. |
| Shipping | set_shipping_address | Set destination, get rates. |
| Shipping | select_shipping_option | Pick a rate. |
| Checkout | quick_checkout | Assemble checkout-ready cart(s) across one or more stores in a single call (creates carts, adds items, sets address). |
| Checkout | execute_checkout | Finalize order (triggers delegation if required). |
| Delegation | request_delegation | Issue an OAuth device code. |
| Delegation | check_delegation | Poll for approval status. |
| Delegation | submit_delegation_otp | Approve a request with an emailed one-time passcode. |
| Orders | list_orders | List buyer's past orders. |
| Orders | get_order | Single order detail. |
| Payments | get_payment_methods | Payment channels + enabled gateways (gateways[]) available for an order. |
| Payments | initiate_payment | Start an in-chat payment (mobile money or card); optional gateway selector; requires delegation. |
| Payments | submit_payment_otp | Submit a mobile-money OTP; requires delegation. |
| Payments | get_payment_status | Poll until the payment is confirmed or fails. |
(The payment tools bring the in-chat checkout flow to MCP clients; the exact surface area grows as the gateway does.)
Inline payments
The four *_payment* tools let an agent collect payment inside the chat for an order that already exists, without sending the buyer to a hosted checkout page. The flow: get_payment_methods → initiate_payment (mobile money or a hosted card redirect) → submit_payment_otp if an OTP is needed → poll get_payment_status until paid/processing. initiate_payment and submit_payment_otp require a buyer_delegation_token (same as checkout), and site_id falls back to DEFAULT_SITE_ID so only order_id is strictly required.
When a store enables more than one payment gateway, get_payment_methods returns a gateways[] array (e.g. Paystack, Stripe, PayPal). Ask the buyer which they want and pass it as the optional gateway argument (paystack | stripe | paypal) to initiate_payment; omit it to use the store's first enabled gateway. Stripe and PayPal are card/redirect via a hosted Checkout page (PayPal appears only for PayPal-supported currencies); Paystack also offers Ghana mobile money (with the in-chat OTP step).
Interactive cards (MCP Apps)
As of v1.1, Synchronity ships MCP Apps Views (SEP-1865) — interactive UI cards that render directly inside hosts that support them, such as Claude. Instead of returning plain text, discovery and cart tools emit dual output:
- a Markdown summary (so every client, including text-only ones, still gets a readable answer),
structuredContent(the typed AMPS payload), and- a
ui.resourceUripointing at a hosted view underui://synchronity/*.
Three views ship today:
| View | Resource | Backed by |
|---|---|---|
| Single product | ui://synchronity/product | get_product, search_products (single result) |
| Product list | ui://synchronity/product-list | search_products, compare_products |
| Cart | ui://synchronity/cart | create_cart, get_cart, add_to_cart, remove_from_cart |
Hosts that don't understand the views simply fall back to the Markdown — there's no degraded experience. The view bundles ship inside the .mcpb (and the hosted MCP serves them), so no extra setup is required.
Tool authentication
The MCP server reads GATEWAY_URL, AIT_TOKEN, and DEFAULT_SITE_ID from env — all optional (GATEWAY_URL defaults to the hosted gateway; with no AIT_TOKEN the server auto-registers its own identity on first run). Every tool call attaches the AIT as a Bearer token; the gateway enforces scope. Tools that mutate (cart, checkout) check that the AIT carries manage_cart or execute_checkout respectively — wrong scope returns 403 forbidden_scope before the connector is touched.
Adding a custom tool
The MCP layer is a thin shell over the REST gateway — it holds no business logic of its own. New capabilities are added as gateway routes and surfaced as MCP tools, so there's a single source of truth.
Reference clients
Typed clients are published for TypeScript, Python, Go, and PHP, so you can call the gateway directly without the MCP layer.