# 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 five 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. |
| `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.
- 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**