Catalog API & MCP

A growing share of shoppers ask an AI assistant before they ever open a search engine. Solidshop makes sure those assistants can actually find your products: every store exposes a read-only catalog API in two flavours — conventional REST endpoints, and an MCP server that agent runtimes such as Claude can call directly as tools. Both are part of the free core, enabled on install, and require no setup.

The design principle behind both surfaces: every response carries the canonical URL of the page it describes. When an assistant recommends one of your products, the shopper lands on your storefront — your product page, your cart, your checkout. The API is a discovery layer, not a sales channel of its own.

What is (and is not) exposed

The catalog API is a guest. It serves exactly the data an anonymous visitor sees in your storefront HTML — published products, categories and brands on public access levels, in your store’s enabled languages and display currencies. Nothing more:

  • Stock is a yes/no answer. The API says whether a product or variant is in stock — never how many units you hold.
  • No cost prices. Your margins are yours.
  • No customer or order data. The API has no orders, no carts, no accounts — it is read-only catalog discovery, nothing else.
  • Hidden stays hidden. Unpublished or access-restricted products answer exactly like products that don’t exist.

The REST endpoints

All endpoints are GET, served by Joomla’s API application under your site’s /api path:

GET /api/index.php/v1/solidshop/products
GET /api/index.php/v1/solidshop/products/{id}
GET /api/index.php/v1/solidshop/products/{id}/variants
GET /api/index.php/v1/solidshop/categories
GET /api/index.php/v1/solidshop/categories/{id}
GET /api/index.php/v1/solidshop/brands
GET /api/index.php/v1/solidshop/brands/{id}

The products list accepts filter[search], filter[category], filter[brand], filter[min_price] / filter[max_price], filter[in_stock], sort and JSON:API paging (page[limit], capped at 50). Add lang=de-DE on a multilingual site to get translated content, and currency=USD to get prices converted into any display currency you have enabled — the same conversion your storefront’s currency switcher uses.

filter[category] lists a product under its main category and under each of its additional categories, as the storefront does. A product’s category is its main category; the list adds additional_category_ids and the single product additional_categories (id, title and listing URL of each), both limited to categories a guest may open. The MCP tools do the same: solidshop_search_products lists through either route for its category_id and returns additional_category_ids, and solidshop_get_product returns additional_categories with an “Also listed in” line.

A single product carries specifications: the rows of the product page’s Specifications tab, in its order — the custom fields shown there, then the product’s own specification rows. Each entry has a label, a plain-text value, and a source: field for a custom field, whose name is the field’s machine name and which is shared across products, or product for a row typed on this product alone, whose name is empty. The MCP tool solidshop_get_product returns the same list.

The MCP server

MCP (Model Context Protocol) is the standard AI agents use to call external tools. Your store’s MCP endpoint lives at:

https://www.example.com/api/index.php/v1/solidshop/mcp

It serves five read-only tools:

  • solidshop_search_products — free-text search with category, brand, price and availability filters
  • solidshop_get_product — one product in full detail: description, images, the categories that list it, options, per-variant price and availability, specifications
  • solidshop_list_categories — the category tree with product counts (a product counted in its main category)
  • solidshop_list_brands — brands with product counts
  • solidshop_get_store_info — store profile: contact details, currencies, languages, policy pages

To try it yourself with Claude Code, connect your store as an MCP server:

claude mcp add --transport http my-store \
    https://www.example.com/api/index.php/v1/solidshop/mcp

…then ask something like “what does my store sell under €50?”. Any MCP-capable client works the same way — the server speaks the standard Streamable HTTP transport, stateless, one JSON-RPC request per call. For a quick protocol-level check without an AI client, the official inspector works too: npx @modelcontextprotocol/inspector@latest.

For a walkthrough with a worked example — connecting a store, a full assistant conversation showing the tool calls, and why the endpoint is open by default — see How to connect your Joomla store to an AI assistant with MCP.

SEF URLs — if your server rewrites URLs, the shorter /api/v1/solidshop/… form works as well. The /api/index.php/ form works on every install, so the examples use it.

Discovery: llms.txt

An MCP server is only useful to an agent that knows it exists. A shopping assistant, a research agent or an LLM answering “does this shop sell X” lands on your store knowing nothing but the domain — and the one root path such agents check is /llms.txt. Solidshop serves it out of the box:

https://www.example.com/llms.txt

It is a short Markdown document, rendered live on every request from your store’s own data — nothing is written to disk, so a renamed category or a changed returns page shows up on the next fetch. It contains:

  • the store name, a one-line summary you write, and the country, currencies and languages the store trades in
  • the MCP endpoint with its tool names, the REST routes and the XML sitemap — each only when it actually answers (the MCP and REST lines disappear if you switch public access off, see below)
  • up to 50 top-level categories that have at least one visible product, linked to their canonical pages
  • the policy pages configured on the store’s Policies tab, and the store email and phone
  • free-text notes you write — wholesale terms, shipping days, anything an assistant should know
  • a one-line credit that the store runs on Solidshop for Joomla

The file is declarative: it states what exists and where, and never instructs the agent. Products are deliberately not listed — the sitemap and the API carry the catalogue, and the file stays a stable pointer document.

Three URLs

  • /llms.txt — the path agents fetch. Needs Joomla’s URL rewriting on, like any SEF URL. On a multilingual site that requires the language code in URLs it answers with a 301 to the raw URL below first; every agent follows it.
  • index.php?option=com_solidshop&view=llms&format=raw — the same document at a permanent raw URL that works on every host, rewriting or not. Open it from System → Overview to check what agents will read.
  • …&view=llms&format=raw&store_id={id} — one store’s document, shown on that store’s SEO tab. Switch Per-store documents off under Options → AI discovery if you would rather not expose which categories belong to which store.

What you write

Two fields on the store’s SEO tab: Store summary for AI agents (one plain-text line, up to 300 characters — it is also the store description the solidshop_get_store_info tool returns) and Notes for AI agents (Markdown). Headings inside the notes are flattened so the file keeps its structure. Everything else in the file comes from data you already manage.

Switches

Options → AI discovery (llms.txt): serve the file, per-store documents, list categories, and the platform credit — all on by default. The credit is your call: it is your domain.

Your own file wins

If you would rather hand-write the file, drop an llms.txt into the web root. Joomla’s .htaccess only routes missing files to index.php, so a physical file takes over with no setting — and takes over maintenance with it. The same is true for generic Joomla llms.txt generators, which know your menus and articles but not your shop: their file replaces Solidshop’s, MCP line and policies included.

Check robots.txt. Joomla’s stock robots.txt ships Disallow: /api/, which keeps every crawler that honours it away from the catalog routes llms.txt points at. System → Overview flags it; the go-live checklist has the one line that reopens just the Solidshop routes.

Turning it off, or requiring a token

Everything the API serves is already public on your storefront, so public access is the default and the right choice for almost every store — an AI assistant that cannot read your catalog anonymously simply moves on to a competitor’s.

If you still want to close it: System → Plugins → Web Services - Solidshop has a single Public catalog access switch. Set it to No and every catalog route — the MCP endpoint included — requires a Joomla API token; anonymous requests get a 401. Disabling the plugin removes the routes entirely.

Crawl load and rate limiting

Catalog responses are served with Cache-Control: public headers, so a reverse proxy or CDN in front of your site (LiteSpeed cache, Cloudflare, Varnish) absorbs repeat reads without touching PHP. Rate limiting is deliberately left to the server layer, where it belongs — use your host’s tools (fail2ban, LiteSpeed per-IP limits, Cloudflare rules) if an aggressive crawler ever needs reining in. The API itself does nothing a guest browsing your storefront couldn’t do.