MCP server for AI agents
With the Garanify MCP server, Claude, Cursor and other MCP clients work with your shop directly: find invalid products, explain why a label is missing, test values in a preview and fix them.
The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.
The server runs locally over stdio (JSON-RPC 2.0, MCP versions 2025-06-18, 2025-03-26, 2024-11-05) and only calls documented API endpoints through the Node.js SDK. It is built and tested but not published on npm yet; until then you start it from the repository.
Configure
{
"mcpServers": {
"garanify": {
"command": "node",
"args": ["/path/to/gewaehrleistung/packages/mcp/src/cli.js"],
"env": {
"GARANIFY_API_KEY": "gfy_sk_test_…",
"GARANIFY_BASE_URL": "http://localhost:8788",
"GARANIFY_MCP_READONLY": "1"
}
}
}
} claude mcp add garanify \
--env GARANIFY_API_KEY=gfy_sk_test_… \
--env GARANIFY_BASE_URL=http://localhost:8788 \
-- node /path/to/gewaehrleistung/packages/mcp/src/cli.js | Variable | Meaning |
|---|---|
GARANIFY_API_KEY | Secret key of the shop. Start with a test key (gfy_sk_test_…). The server refuses publishable keys. |
GARANIFY_BASE_URL | Default https://api.garanify.com (in preparation), local http://localhost:8788. |
GARANIFY_SHOP | Shop ID, optional; otherwise from GET /v1/me. |
GARANIFY_MCP_READONLY | 1 = only reading tools. Recommended for assistants that should not change data. |
Tools
Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so the client can ask before writing. This list is built from the server code.
| Tool | Kind | Description (as the agent sees it) |
|---|---|---|
garanify_overview | read | Shop, plan, GARAN allowance and counts of products per status (label, none, hidden, invalid). Call this first. |
garanify_list_products | read | One page of products (sorted by SKU) with their resolved label and errors. Use nextCursor for the next page. |
garanify_list_invalid_products | read | All products with status "invalid" and the reasons (years_too_low, years_not_half, brand_missing, model_missing, …). These are compliance gaps to fix. |
garanify_get_product | read | A stored product with its resolved label. |
garanify_explain_label | read | Which GARAN label a stored product shows and why (own value, main product, rule number, hidden, invalid, no years), with the alternative text in the given language. |
garanify_preview_label | read | Resolves product values against the rules of the shop without storing anything. Use it to check values before garanify_upsert_product. |
garanify_upsert_product | write | Stores the product under its SKU (replaces all fields). Invalid guarantee data is stored with status "invalid" and shows no label. On Free, adding a label beyond the allowance fails with garan_limit_reached. |
garanify_bulk_upsert_products | write | Atomic bulk upsert (Pro and Agency). If one item does not match the schema, nothing is written. |
garanify_delete_product | write, destructive | Deletes the product. Its label disappears from the shop. Only on explicit request of the user. |
garanify_list_rules | read | Ordered rules (brand, category, tag → years). The first matching rule applies; product values always win. |
garanify_replace_rules | write, destructive | Replaces the whole ordered rule list (Pro and Agency). Read the current rules first and send the complete new list. |
garanify_render_label | read | The official GARAN label as SVG: for a stored product (sku) or for given values (years, brand, model). Invalid values return the reason. |
garanify_export_evidence | read | Evidence of what the shop shows: notice rows per language and one row per product with GARAN data. Pro and Agency. |
garanify_update_notice_settings | write | Changes where the notice appears (product, cart, checkout, footer, email), its width and the product label display (full or nested). The notice is a legal duty: do not disable it unless the shop shows it another way. |
garanify_webhook_status | read | The webhook endpoint of the shop (URL, events, last outcome) and the latest deliveries (delivered, rejected, unreachable, pending). |
garanify_languages | read | The 24 EU languages with the official notice title and the GARAN term. |
Errors and safety
- API errors come back as tool errors with the stable
code,errorsandrequestId, so the agent can correct its input (errors and codes). - Arguments are checked against the input schema before the call; the server rejects unknown fields.
- Give the agent a test key and
GARANIFY_MCP_READONLY=1first. The key stays on your machine; the server only sends it to the base URL.
Instructions for the agent
On connect, the server sends these instructions:
Garanify shows the EU notice on the legal guarantee and the GARAN label (Implementing Regulation (EU) 2025/1960) in online shops.
- The GARAN label appears only for a free producer guarantee of MORE than 2 years, in whole or half years, with brand and model identifier.
- The model identifier is garan.model, otherwise the MPN, otherwise the SKU. Never use a GTIN/EAN as model.
- Product values win over rules; variants inherit from their main product (parentSku); the first matching rule applies.
- Start with garanify_overview. Use garanify_explain_label before changing data, and garanify_preview_label to test values without saving.
- Products with status "invalid" show no label: fix them with garanify_list_invalid_products and garanify_upsert_product.
Not legal advice.