MCP Server
The 22 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 22 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 22 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. |
| Cart | create_cart | Open a new cart on a site. |
| Cart | add_to_cart | Add a product variant + quantity. |
| Cart | remove_from_cart | Remove a line item. |
| Cart | get_cart | Fetch current cart state. |
| Cart | apply_coupon | Apply a discount code. |
| Shipping | set_shipping_address | Set destination, get rates. |
| Shipping | select_shipping_option | Pick a rate. |
| 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 available for an order. |
| Payments | initiate_payment | Start an in-chat payment (mobile money or card); 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 Paystack-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.
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. 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.