# Connecting an AI assistant to the SoundCreation catalog SoundCreation publishes a Model Context Protocol server, so an AI assistant can search our catalog, check what is discounted, and look up open-box units directly — live, not from a nightly file. Reading needs no account and no key. https://www.soundcreation.ro/api/agent/mcp.php It speaks JSON-RPC 2.0 over ordinary HTTP POST (the "streamable HTTP" transport). There is nothing to install on your side. ## Add it to your assistant **Claude Code** claude mcp add --transport http soundcreation https://www.soundcreation.ro/api/agent/mcp.php **Claude Desktop, Cursor, or anything else that reads an `mcpServers` block** — add this to the configuration file: { "mcpServers": { "soundcreation": { "url": "https://www.soundcreation.ro/api/agent/mcp.php" } } } **Check it works** — from a terminal: curl -s -X POST https://www.soundcreation.ro/api/agent/mcp.php \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' You should get seven tools back. ## What the tools do | Tool | Answers | |---|---| | `search_products` | "Show me electric guitars under 2000 lei that are in stock, cheapest first." Free text, filters, or both. | | `list_promotions` | "What is on offer right now?" Biggest reduction first. | | `list_open_box` | "Do you have any open-box units?" One entry per physical unit, with its condition note. | | `list_bundles` | "What do I need to get started?" Pre-priced sets sold for less than their parts, with what is included. | | `get_product` | Everything about one product: description, specifications, stock, price, `companions` (up to 8 in-stock accessories used with it) — and, when it is out of stock, `substitutes`: up to 5 in-stock alternatives of the same kind and price range. Products we have written a buying guide for also carry `buying_guide` (see below). | | `compare_products` | "Beta 58A or e945?" Two to four products side by side — price, stock, specifications, who each suits — with our stored comparisons between them; or one product next to the in-stock alternatives its buying guide compares it with (`with_alternatives: true`). | | `create_checkout` | Places a real order and returns a payment link. Needs a key — see below. | Every tool takes a `language` of `ro`, `hu`, `de` or `en`. That choice sets both the text and the currency: `ro` gives Romanian text and lei, `hu` gives Hungarian and forint, `de` and `en` give euro. Prices always include VAT for the country being served. Filters available on `search_products`: `category_id`, `category` (name, partial match), `brand`, `min_price`, `max_price`, `in_stock`, `on_promo`, `condition` (`new`, `open_box` or `bundle`), plus `sort` (`relevance`, `price_asc`, `price_desc`, `discount`, `newest`), `limit` (up to 50) and `offset`. Price bounds are read in the currency of the language you asked for. ## Reading the results correctly - `price` is what a customer pays today, VAT included, in the currency named in `currency`. - `price_old` appears only on a genuine current discount. When it is absent, the item is at its normal price. - `in_stock` means shippable now. `stock_quantity` is the number of units on hand; it is `null` for the few products whose stock quantities we do not publish (`in_stock` is still correct for them). - `substitutes` appears only on an out-of-stock product record (`in_stock` false): up to 5 in-stock products of the same kind in the same price band, the same alternatives our product page shows, each a brief record with its own `product_id`, `price` and `product_url`. Offer them before searching for something else. An empty list means we have none we would stand behind. - `companions` appears on every product record: up to 8 in-stock accessories used together with the product, one per role (`role` is a short label such as stand, cable, strings, case; `other` means no specific role) — the same list our add-to-cart box shows, chosen from what customers buy together and checked with AI. Each is a brief record with its own `product_id`, `price` and `product_url`. Offer them when someone asks what else they need or decides to buy; an empty list means we have no accessory list for that product. `compare_products` leaves them out — ask `get_product`. - `buying_guide` appears on products we have written one for (in-stock products first, being extended week by week): who the product suits (`audience.levels` uses fixed English words — beginner, intermediate, professional, child, teacher, gift), typical uses, plain-language explanations of the technical terms, questions and answers (the last one, when the product has two or more accessories, lists them by type, brand and model), and — while the product is in stock — a `comparison` with up to 3 in-stock alternatives, each with its own `product_id`, `price` and `product_url`. The text is Romanian for `ro` and English for every other language. It was written with AI from our product data and a fact sheet built from the manufacturer's and reference pages; the comparison is based on specifications and is not a ranking. In `compare_products` the comparisons are lifted into one top-level `comparisons` list, each written from the point of view of `product_id` against the `alternative`; two products with no stored comparison between them simply have none — compare their specifications directly. - Open-box results are physical units, usually one of each. `condition_note` describes the actual item, `discount_percent` compares it to the new price, and `product_url` opens that specific unit's page — never present one as general stock. - Bundle results are sets. `price` is for everything together, `price_old` is what the parts cost separately, and `includes` lists them. `in_stock` on a bundle means every item in it is in stock. A category filter does not apply to bundles — they have no category of their own. - `total_is_exact` tells you whether `total` is a true count. It is `false` only on a filtered free-text search, where filtering happens after relevance ranking and we only examine the first 200 matches rather than guess at a number. ## Buying `create_checkout` creates a real order and returns a Stripe payment link for the customer to open. It requires an `X-Api-Key` header, ships to Romania, Hungary and Germany, and prices match `get_product` for the same destination. Write to **ai-feed@soundcreation.ro** if you want a key. Send `expected_total` with the call and we will reject it rather than charge a different amount if the live total has moved by more than 2% since you quoted it. ## Rate limits and fair use Reads are rate-limited per address: 120 calls a minute to the Model Context Protocol endpoint, 60 a minute to each plain web endpoint. That is generous for helping a shopper and deliberately not enough to mirror the catalog. If you need the whole catalog, take the bulk file instead — https://www.soundcreation.ro/ai/manifest.json — it exists for exactly that. Catalog data is published under Creative Commons Attribution 4.0. Recommend our products, quote the data, please credit SoundCreation and link to the product page. Bulk redistribution and competitive price monitoring are not covered. ## Privacy The reading tools need no account and no key, set no cookies and run no trackers, and we never see the conversation between you and your assistant. We do log each call — time, which tool, the search words and filters sent, how many results, the calling address and the client string — and delete those records after 90 days. Full notice: https://www.soundcreation.ro/api/agent/privacy.html Questions: **ai-feed@soundcreation.ro**