MCP server

Reference for the Haszno MCP server — install, configuration, and all 51 implemented tools with input schemas and examples.

Overview

The Haszno MCP server (haszno-mcp) exposes the Haszno API as a set of haszno_* tools to any MCP-compatible AI agent client: Claude Code, Claude Desktop, Cursor, and others. It communicates over stdio using the Model Context Protocol.

The MCP server reads its credentials from environment variables or from the config file ~/.config/haszno/config.json. That file is written by the CLI command haszno login (or by the haszno_account_configure tool). The CLI reads the same file, so one login configures both; flags and environment variables take precedence over it.

Transport

The server uses StdioServerTransport from @modelcontextprotocol/sdk. Every MCP client that supports stdio-based servers is compatible.

Installation

Recommended: unified installer

The one-step installer in the skill repo installs the MCP server, the CLI, and the agent skill together:

curl -fsSL https://raw.githubusercontent.com/haszno-labs/haszno-skill/main/install.sh | bash

What the script does:

1. Clones haszno-mcp (and haszno-cli, haszno-skill) into ~/.haszno/.
2. Runs npm install && npm run build for the MCP server.
3. Registers the server with Claude Code: claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js (skipped if claude is not found).
4. Copies the skill files to ~/.claude/skills/haszno/.

Manual install

git clone https://github.com/haszno-labs/haszno-mcp ~/.haszno/haszno-mcp
cd ~/.haszno/haszno-mcp
npm install
npm run build

Then register with your client (see Client setup).

Client setup

Claude Code

claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js

Generic mcpServers JSON

Use this block in claude_desktop_config.json, .cursor/mcp.json, or any MCP client config that accepts mcpServers:

{
  "mcpServers": {
    "haszno": {
      "command": "node",
      "args": ["~/.haszno/haszno-mcp/dist/index.js"],
      "env": {
        "HASZNO_API_URL": "https://haszno.com",
        "HASZNO_API_KEY": "your-api-key"
      }
    }
  }
}

npx variant

The packages are not published to the npm registry (both have "private": true in package.json). An npx command referencing the GitHub source works if you have Node 20+ and network access:

claude mcp add haszno -- npx -y github:haszno-labs/haszno-mcp

Configuration

Environment variables

Config file

The MCP server reads ~/.config/haszno/config.json and, if that file does not exist, ~/.config/arfutar/config.json. The file is written by the CLI command haszno login or by the haszno_account_configure tool. Unlike the CLI, the MCP server does not check that the saved key belongs to the URL in use: if you override HASZNO_API_URL for the MCP server, set HASZNO_API_KEY explicitly as well.

{
  "apiUrl": "https://haszno.com",
  "apiKey": "haszno_live_..."
}

Instead of apiKey, the file can hold basicAuth (user:pass).

Precedence (highest to lowest)

1. HASZNO_API_URL / HASZNO_API_KEY / HASZNO_BASIC environment variables.
2. ARFUTAR_API_URL / ARFUTAR_API_KEY / ARFUTAR_BASIC environment variables (legacy fallback, used only when the matching HASZNO_* variable is not set).
3. ~/.config/haszno/config.json.
4. ~/.config/arfutar/config.json.

The config file is read only when neither an API key nor Basic credentials come from the environment, and only once, when the server starts. Restart the MCP server after changing the file. The API key is always sent as the x-api-key header; Basic credentials are used only when there is no API key.

What works without credentials

Against https://haszno.com the following tools work without an API key and return synthetic demo data: haszno_ping, haszno_account_get_stats, haszno_account_get_impact, haszno_account_get_settings, haszno_account_list_suppliers, haszno_orders_list, haszno_orders_get, haszno_proposals_list, haszno_proposals_market, haszno_import_list_list, haszno_peers_invite_list, and haszno_blog_latest. haszno_feeds_outbound_info without fetch_summary and haszno_account_configure make no API call at all.

All other tools — every write tool, and read tools such as haszno_catalog_*, haszno_catalogue_search, haszno_connections_list, haszno_ideas_list and the haszno_rules_* / haszno_automation_get readers — return 401 without credentials.

Implemented tools

The server registers exactly 51 tools in 11 domains. The tools for the twelfth domain, own-shop products, are not implemented yet — see Planned tools.

The confirm parameter

Most write tools take a confirm parameter, but it behaves in one of four ways. Each tool's parameter table says which one applies:

• true (literal): the schema accepts only true. Omitting it or passing false fails input validation, and nothing is sent.
• boolean, preview on false: confirm is required. With false the tool returns a preview and makes no API call.
• boolean, error on false: confirm is required. With false the tool returns a "Safety gate" error and makes no API call.
• boolean, default false: confirm is optional. When omitted or false, the tool returns a dry-run summary and makes no API call.

The badge shows whether the tool changes data: Read-only tools only read (some still need confirm: true because they can start a paid AI call), and Write tools change data.

Account & settings

haszno_ping

Calls GET /api/health. Read-only

When to call: before any other tool, to verify connectivity.

Input parameters: none.

Returns: { ok: true } on success.

Example call:

{
  "name": "haszno_ping",
  "arguments": {}
}

haszno_account_get_stats

Returns a dashboard snapshot of the shop (GET /api/stats). Read-only

When to call: at the start of a daily health check, or when the user asks for an overview.

Input parameters: none.

Returns: an object with:

Example call:

{
  "name": "haszno_account_get_stats",
  "arguments": {}
}

haszno_account_get_impact

Returns the profit impact of Haszno's pricing over the last N days (GET /api/impact). Read-only

When to call: when the user asks about extra profit, margin gains, or automatic order forwarding.

Input parameters:

Returns: { days, extraProfit, baseline, pctGain, orders, autoForwardedOrders } — money values in gross HUF.

Example call:

{
  "name": "haszno_account_get_impact",
  "arguments": { "days": 7 }
}

haszno_account_get_settings

Returns the shop's pricing configuration (GET /api/settings). Read-only

When to call: before proposing any pricing change, and always before haszno_account_update_settings.

Input parameters: none.

Returns: { undercutPct, minMarginPct, vatPct, automationPaused }.

Example call:

{
  "name": "haszno_account_get_settings",
  "arguments": {}
}

haszno_account_list_suppliers

Returns the shop's own supplier integrations — the suppliers whose catalogues have been imported (GET /api/suppliers). This is not the network list; for that, use haszno_catalog_list_suppliers. Read-only

Input parameters: none.

Returns: an array of { id, name, orderMode, email, network, category, country, shopUrl, createdAt }.

Example call:

{
  "name": "haszno_account_list_suppliers",
  "arguments": {}
}

haszno_account_update_settings

Replaces the shop's pricing rules (PUT /api/settings). All three numeric fields are required, so read the current values with haszno_account_get_settings first and send back the ones you do not change. Write

Input parameters:

Returns: the updated settings object.

Example call:

{
  "name": "haszno_account_update_settings",
  "arguments": { "undercutPct": 1, "minMarginPct": 12, "vatPct": 27, "confirm": true }
}

haszno_account_configure

Writes credentials to ~/.config/haszno/config.json (file mode 600), keeping other keys already in the file. It makes no API call. The running server keeps the credentials it loaded at startup, so restart it afterwards. Write

Input parameters:

Provide exactly one of apiKey and basicAuth; the tool returns an error if both or neither are given.

Returns: { saved: true, configFile, apiUrl, authMethod }.

Example call:

{
  "name": "haszno_account_configure",
  "arguments": { "apiUrl": "https://haszno.com", "apiKey": "haszno_live_...", "confirm": true }
}

Supplier catalogue (haszno_catalog_*)

The network of partner suppliers the shop can connect to. haszno_catalog_list_categories and haszno_catalog_list_suppliers both fetch GET /api/network/suppliers and filter and paginate locally.

haszno_catalog_list_categories

Read-only

When to call: to find valid category values for haszno_catalog_list_suppliers and haszno_catalog_supplier_products.

Input parameters: none.

Returns: { categories: string[] }, sorted alphabetically.

Example call:

{
  "name": "haszno_catalog_list_categories",
  "arguments": {}
}

haszno_catalog_list_suppliers

Read-only

Input parameters:

Returns: { suppliers: [{ id, name, category, country, connected, productCount, avgResellerMarginPct, shopUrl }], total, page, pages }.

Example call:

{
  "name": "haszno_catalog_list_suppliers",
  "arguments": { "category": "kert", "limit": 10 }
}

haszno_catalog_supplier_products

Returns products from a partner supplier's catalogue (GET /api/network/suppliers/:id/products), filtered and paginated locally. Read-only

Input parameters:

Returns: { products: [{ id, sku, name, ean, category, wholesaleNet, rrpGross, stock, potentialMargin }], total, page, pages }. wholesaleNet is net HUF; rrpGross and potentialMargin.priceGross are gross HUF.

Example call:

{
  "name": "haszno_catalog_supplier_products",
  "arguments": { "supplier_id": 3 }
}

haszno_catalog_supplier_view

Returns supplier metadata and, per product, aggregated reseller-market statistics (GET /api/network/supplier-view/:supplierId): resellerCount, minGross / avgGross / maxGross, belowRrp, lossCount, and saturation (0–100). Read-only

When to call: to evaluate a supplier before connecting it.

Input parameters:

Example call:

{
  "name": "haszno_catalog_supplier_view",
  "arguments": { "supplier_id": 3 }
}

haszno_catalog_connect_supplier

Connects a partner supplier and imports all its products into the shop (POST /api/network/suppliers/:id/connect). Write

Input parameters:

Returns: { status, imported, skipped }.

Example call:

{
  "name": "haszno_catalog_connect_supplier",
  "arguments": { "supplier_id": 3, "confirm": true }
}

haszno_catalog_sync_supplier

Synchronises wholesale prices and stock from a connected partner supplier (POST /api/network/suppliers/:id/sync). Write

Input parameters:

Returns: { costChanges, stockOuts, total }.

Example call:

{
  "name": "haszno_catalog_sync_supplier",
  "arguments": { "supplier_id": 3, "confirm": true }
}

Partner catalogue search and import list

haszno_catalogue_search

Searches the partner product catalogue (GET /api/catalogue/products). Read-only

When to call: when the user wants to discover new products to list.

Input parameters:

Returns: { items, total, facets }.

Example call:

{
  "name": "haszno_catalogue_search",
  "arguments": { "cats": "kert", "minMarginPct": 20, "inStock": true, "sort": "margin_desc" }
}

haszno_import_list_list

Lists the items on the import list, the staging area between the catalogue and a webshop (GET /api/import-list). Read-only

Input parameters:

Returns: { items, total }.

Example call:

{
  "name": "haszno_import_list_list",
  "arguments": { "status": "varakozik" }
}

haszno_import_list_add

Adds catalogue products to the import list (POST /api/import-list). No product is created in a webshop until haszno_import_list_push runs. This tool has no confirm parameter. Write

Input parameters:

Returns: { added, skipped } — skipped counts products already on the list.

Example call:

{
  "name": "haszno_import_list_add",
  "arguments": { "networkProductIds": [101, 102, 103] }
}

haszno_import_list_push

Pushes import-list items to a connected webshop. The connection must have status kapcsolva (check with haszno_connections_list). Write

Input parameters:

Example call:

{
  "name": "haszno_import_list_push",
  "arguments": { "ids": [201, 202], "targetConnectionId": 5, "confirm": true }
}

Store connections

haszno_connections_list

Lists the shop's webshop connections (GET /api/connect/stores); the status filter is applied locally. Read-only

When to call: before haszno_import_list_push, to find the targetConnectionId.

Input parameters:

Returns: { connections: [{ id, platform, name, status, domain, lastError, connectedAt, lastSyncAt }] }.

Example call:

{
  "name": "haszno_connections_list",
  "arguments": { "status": "kapcsolva" }
}

Price proposals

haszno_proposals_list

Lists price proposals (GET /api/proposals). The product filter and the pagination are applied locally. Read-only

Input parameters:

Returns: { _meta: { total, offset, limit, hasMore }, proposals: [{ id, productId, productName, productSku, oldPriceGross, proposedPriceGross, diffGross, reason, source, status, batchId, createdAt, decidedAt }] }.

Example call:

{
  "name": "haszno_proposals_list",
  "arguments": { "status": "pending" }
}

haszno_proposals_market

Returns a product with its current, recommended and market prices, plus its pending proposals, newest first. It reads GET /api/products and GET /api/proposals?status=pending. Read-only

When to call: before approving or rejecting a product's proposals.

Input parameters:

Returns: { product: { id, sku, name, supplierName, costNet, stock, listed, current, recommended, market, rrpGross }, pendingProposals: [...] }.

Example call:

{
  "name": "haszno_proposals_market",
  "arguments": { "productId": 42 }
}

haszno_proposals_approve

Approves proposals and applies the prices immediately (POST /api/proposals/approve). Save the returned batchId — haszno_proposals_rollback needs it. Write

Input parameters:

Returns: { batchId, applied, note }.

Example call:

{
  "name": "haszno_proposals_approve",
  "arguments": { "ids": [42, 43], "confirm": true }
}

haszno_proposals_reject

Rejects proposals (POST /api/proposals/reject). Prices do not change; the proposals stay in the history with status rejected. Write

Input parameters:

Returns: { rejected, note }.

Example call:

{
  "name": "haszno_proposals_reject",
  "arguments": { "ids": [44], "confirm": true }
}

haszno_proposals_rollback

Restores the prices from before an approved batch (POST /api/proposals/rollback); the proposals change to rolled_back. Write

Input parameters:

Returns: { rolledBack, note }.

Example call:

{
  "name": "haszno_proposals_rollback",
  "arguments": { "batchId": "b-1234abcd", "confirm": true }
}

Automation rules

haszno_automation_get

Returns the global automation kill switch (GET /api/automation). While paused is true, proposal approval returns HTTP 409. Read-only

Input parameters: none.

Returns: { paused: boolean }.

Example call:

{
  "name": "haszno_automation_get",
  "arguments": {}
}

haszno_rules_list_templates

Lists the built-in rule templates (GET /api/rules/templates), for example keszlet_or (stock-out protection), arjavaslat (price proposal on market update), felar_savok (markup tiers) and veszteseg_riasztas (loss alert). Read-only

Input parameters: none.

Returns: each template's key, name, description, trigger, conditions and actions.

Example call:

{
  "name": "haszno_rules_list_templates",
  "arguments": {}
}

haszno_rules_list

Lists the shop's automation rules (GET /api/rules). Read-only

Input parameters: none.

Returns: each rule's id, name, enabled flag, trigger, conditions, actions, template key and creation date.

Example call:

{
  "name": "haszno_rules_list",
  "arguments": {}
}

haszno_rules_list_runs

Returns the rule execution log, newest first (GET /api/rule-runs). Entries whose summary starts with "Levéve" are unlists that haszno_rules_undo_unlists can reverse. Read-only

Input parameters:

Returns: entries with run id, rule id, rule name, trigger, product id (or null), summary and timestamp.

Example call:

{
  "name": "haszno_rules_list_runs",
  "arguments": { "limit": 10 }
}

haszno_rules_create

Creates a rule (POST /api/rules). Write

Input parameters:

Returns: the created rule with its id.

Example call:

{
  "name": "haszno_rules_create",
  "arguments": {
    "name": "Unlist when out of stock",
    "trigger": "feed_import",
    "conditions": [{ "field": "stock", "op": "lte", "value": 0 }],
    "actions": [{ "type": "unlist" }],
    "confirm": true
  }
}

haszno_rules_update

Updates a rule (PATCH /api/rules/:id). Only the fields you send change. Write

Input parameters:

Example call:

{
  "name": "haszno_rules_update",
  "arguments": { "id": 7, "enabled": false, "confirm": true }
}

haszno_rules_delete

Permanently deletes a rule and its entire run history (DELETE /api/rules/:id). This cannot be undone; to stop a rule reversibly, use haszno_rules_update with enabled: false. Write

Input parameters:

Example call:

{
  "name": "haszno_rules_delete",
  "arguments": { "id": 7, "confirm": true }
}

haszno_rules_run

Runs one rule against all eligible products, regardless of its trigger (POST /api/rules/:id/run). Write

Input parameters:

Returns: { applied, skipped, errors }.

Example call:

{
  "name": "haszno_rules_run",
  "arguments": { "id": 7, "confirm": true }
}

haszno_rules_run_all

Runs all enabled rules whose trigger is manual (POST /api/rules/run-all). Write

Input parameters:

Returns: aggregate { applied, skipped, errors }.

Example call:

{
  "name": "haszno_rules_run_all",
  "arguments": { "confirm": true }
}

haszno_rules_trigger

Fires all enabled rules that listen to a trigger event (POST /api/rules/trigger). Write

Input parameters:

Returns: aggregate { applied, skipped, errors }.

Example call:

{
  "name": "haszno_rules_trigger",
  "arguments": { "trigger": "market_price", "confirm": true }
}

haszno_rules_undo_unlists

Re-lists products that a rule unlisted and marks those log entries as reversed (POST /api/rule-runs/undo). Only entries whose summary starts with "Levéve" and that are not reversed yet are affected. Write

Input parameters:

Returns: { relisted }.

Example call:

{
  "name": "haszno_rules_undo_unlists",
  "arguments": { "ids": [311, 312], "confirm": true }
}

haszno_automation_set

Turns the global automation kill switch on or off (PUT /api/automation). Setting the current state again is harmless. Write

Input parameters:

Returns: { paused }.

Example call:

{
  "name": "haszno_automation_set",
  "arguments": { "paused": true, "confirm": true }
}

Orders

Money values are whole forints, gross. Order statuses: received, forwarded, shipped, error.

haszno_orders_list

Fetches GET /api/orders and returns compact rows without the event log; the status filter and the limit are applied locally. Read-only

Input parameters:

Returns: { orders: [{ id, externalId, customerName, address, status, totalGross, supplierOrderId, trackingNumber, itemCount, createdAt }], total, showing }.

Example call:

{
  "name": "haszno_orders_list",
  "arguments": { "status": "forwarded" }
}

haszno_orders_get

Returns one order with its items, event log, supplier order ID and tracking number. It searches the list returned by GET /api/orders. Read-only

Input parameters:

Example call:

{
  "name": "haszno_orders_get",
  "arguments": { "id": 123 }
}

haszno_orders_ship

Marks an order as shipped (POST /api/orders/:id/ship). Use it for orders in forwarded state; calling it again on a shipped order is safe. Write

Input parameters:

Returns: the updated order.

Example call:

{
  "name": "haszno_orders_ship",
  "arguments": { "id": 123, "confirm": true }
}

haszno_orders_receive

Injects a new order into the forwarding pipeline (POST /api/webhooks/order). Every SKU must already exist in the shop's products. Write

Input parameters:

Returns: { id } of the new order.

Example call:

{
  "name": "haszno_orders_receive",
  "arguments": {
    "externalId": "WC-9001",
    "customerName": "Kovács János",
    "address": "Budapest, Fő utca 1.",
    "items": [{ "sku": "DEMO-5", "qty": 2 }],
    "confirm": true
  }
}

haszno_orders_create_demo

Creates a random demo order from in-stock products (POST /api/demo/order). Write

Input parameters:

Returns: { id } of the new order.

Example call:

{
  "name": "haszno_orders_create_demo",
  "arguments": { "confirm": true }
}

Ideas

haszno_ideas_list

Fetches GET /api/recommendations, then filters, sorts by trend score and margin, and limits the list locally. Read-only

Input parameters:

Returns: { anchor, geo, total, filtered, truncated, items: [{ rank, id, sku, name, supplier, stock, costNet_HUF, suggestedPriceGross_HUF, marginNet_HUF, marginPct, trendScore }] }.

Example call:

{
  "name": "haszno_ideas_list",
  "arguments": { "min_score": 50, "limit": 10 }
}

haszno_ideas_ai_shortlist

Asks the AI for up to 5 products that best fit the shop (POST /api/recommendations/ai). It changes no data, but it can start a paid AI call; the server returns a cached result (cached: true) for 24 hours when the inputs are unchanged. Read-only

Input parameters:

Returns: { summary, cached, picks: [{ productId, networkProductId, name, supplier, recommendedPriceGross_HUF, marginNet_HUF, marginPct, fit, aiReason }], usage }.

Example call:

{
  "name": "haszno_ideas_ai_shortlist",
  "arguments": { "confirm": true }
}

haszno_ideas_ai_description

Generates a Hungarian webshop description for one of the shop's products (POST /api/products/:id/ai-description). The text is only returned, not saved. Triggers a paid AI call. Read-only

Input parameters:

Returns: { product_id, description }.

Example call:

{
  "name": "haszno_ideas_ai_description",
  "arguments": { "product_id": 55, "confirm": true }
}

haszno_ideas_fill_keywords

Uses AI to fill the missing Google Trends keyword of every product that has none, and saves them (POST /api/trends/keywords). Running it again when nothing is missing returns { updated: 0 }. Write

Input parameters:

Returns: { updated }.

Example call:

{
  "name": "haszno_ideas_fill_keywords",
  "arguments": { "confirm": true }
}

Feeds

Feed content can be passed as text in content or read by the MCP server from filePath. A filePath must end in .csv, .tsv, .txt or .xml and must not be inside a hidden directory (such as ~/.ssh or ~/.config).

haszno_feeds_import_supplier

Imports a supplier's catalogue feed (POST /api/feeds/import): creates new products and updates existing ones matched by SKU, then fires the feed_import rules. Write

Input parameters:

Returns: { created, updated, total }.

Example call:

{
  "name": "haszno_feeds_import_supplier",
  "arguments": { "supplierId": 3, "format": "csv", "content": "sku,name,price\nABC-1,Widget,2990", "confirm": true }
}

haszno_feeds_import_market

Imports competitor market prices from CSV (POST /api/market-prices/import), matching rows to products by SKU, then fires the market_price rules. Re-importing the same CSV sets the same values. Write

Input parameters:

Returns: { matched, total }.

Example call:

{
  "name": "haszno_feeds_import_market",
  "arguments": { "content": "sku,market_price\nABC-1,2890", "confirm": true }
}

haszno_feeds_outbound_info

Returns the URLs of the shop's public feeds: <base>/feed/arukereso.xml and <base>/feed/google.xml, where <base> comes from HASZNO_API_URL / ARFUTAR_API_URL or defaults to https://haszno.com. Read-only

Input parameters:

Returns: { arukereso_url, google_url, note }, or with fetch_summary: true, { arukereso: { url, item_count, sample }, google: { url, item_count, sample } } (an error field replaces the counts if a feed cannot be fetched).

Example call:

{
  "name": "haszno_feeds_outbound_info",
  "arguments": { "fetch_summary": true }
}

P2P peer invites

haszno_peers_invite_list

Lists the invite codes you created (GET /api/peers/invites). Read-only

Input parameters: none.

Returns: { invites: [...] }; each invite has code, supplierId, expiresAt, acceptedBy (null while pending) and revokedAt (null while active).

Example call:

{
  "name": "haszno_peers_invite_list",
  "arguments": {}
}

haszno_peers_invite_create

Creates a single-use invite code that gives another Haszno shop access to one of your suppliers' catalogue (POST /api/peers/invites). Write

Input parameters:

Returns: { code, expiresAt, supplierId }.

Example call:

{
  "name": "haszno_peers_invite_create",
  "arguments": { "supplierId": 3, "expiresAt": "2027-01-01T00:00:00Z", "confirm": true }
}

haszno_peers_invite_accept

Accepts an invite code and creates a partner link (POST /api/peers/invites/:code/accept). The code becomes invalid afterwards. Write

Input parameters:

Returns: the new link { id, supplierId, partner, createdAt }.

Example call:

{
  "name": "haszno_peers_invite_accept",
  "arguments": { "code": "INV-XYZ", "acceptorId": "my-shop", "confirm": true }
}

Blog / market insights

haszno_blog_latest

Returns the latest published market insight posts (GET /api/blog). The data is aggregated from at least 5 shops; no single shop's data is included. Read-only

Input parameters:

Returns: { posts, total }; each post has title, summary, bodyMd, period, periodStart, periodEnd, publishedAt and optional data.

Example call:

{
  "name": "haszno_blog_latest",
  "arguments": { "period": "het", "limit": 3 }
}

Planned tools

The own-shop product tools are listed in the skill's references/tools.md, but the MCP server registers none of them yet. Calling them returns a tool-not-found error.

Until these tools are available, use the CLI equivalents: haszno products list, haszno products update, haszno products listing, haszno products apply-prices, haszno products describe.

See also

• CLI reference — same operations accessible from the terminal.
• Agent skill — workflow recipes and safety rules for agents.
• Authentication — API key and demo credential details.
• Errors and rate limits — error schema and retry guidance.