kaduno-mcp

MCP server for K-Shop — connect Cursor, Claude Desktop, Codex, Windsurf, and other AI agents directly to your commerce platform.

Three servers, one package — select which one to connect to with KADUNO_SERVER:

| Server | KADUNO_SERVER | What it exposes | Auth | | --- | --- | --- | --- | | Admin | admin | Orders, catalog, inventory, customers, platform settings, super-admin control plane — grouped into ~25 domain-router tools covering 200+ actions | API key (staff/operator/admin/super_admin) | | Storefront | storefront (default) | Customer shopping — browse, cart, checkout, orders, returns, B2B company purchasing, bookings | Customer JWT or agent API key | | Public | public | Anonymous catalog browsing + guest checkout — no account required | None (or API key for higher rate limits) |

Quick Start

No clone or install needed — run directly via npx:

{
  "mcpServers": {
    "kshop": {
      "command": "npx",
      "args": ["-y", "kaduno-mcp@latest"],
      "env": {
        "KADUNO_API_KEY": "<your-api-key>",
        "KADUNO_SERVER": "storefront"
      }
    }
  }
}

Add multiple entries to connect to more than one server at once (e.g. admin + storefront) — each entry is an independent stdio process:

{
  "mcpServers": {
    "kshop-admin": {
      "command": "npx",
      "args": ["-y", "kaduno-mcp@latest"],
      "env": {
        "KADUNO_API_KEY": "ak_live_...",
        "KADUNO_SERVER": "admin"
      }
    },
    "kshop-store": {
      "command": "npx",
      "args": ["-y", "kaduno-mcp@latest"],
      "env": {
        "KADUNO_API_KEY": "ak_store_...",
        "KADUNO_SERVER": "storefront"
      }
    }
  }
}

Config Snippets by Client

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "kshop": {
      "command": "npx",
      "args": ["-y", "kaduno-mcp@latest"],
      "env": { "KADUNO_API_KEY": "<your-api-key>", "KADUNO_SERVER": "storefront" }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kshop": {
      "command": "npx",
      "args": ["-y", "kaduno-mcp@latest"],
      "env": { "KADUNO_API_KEY": "<your-api-key>", "KADUNO_SERVER": "admin" }
    }
  }
}

Windsurf

Add to Windsurf's MCP config (Settings → Advanced → MCP Servers), same JSON shape as Cursor above.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.kshop]
command = "npx"
args = ["-y", "kaduno-mcp@latest"]
env = { KADUNO_API_KEY = "<your-api-key>", KADUNO_SERVER = "storefront" }

Generic (any MCP-compatible client)

Run directly over stdio:

KADUNO_API_KEY=<your-api-key> KADUNO_SERVER=storefront npx -y kaduno-mcp@latest

Getting Your API Key

1. Log in to K-Shop admin
2. Navigate to Settings → Agent API Keys (staff/admin) — or use your customer account JWT for the storefront server
3. Create a new key scoped to the store/tenant and permission tier you need
4. public server access does not require a key

Environment Variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | KADUNO_SERVER | No | storefront | Which server to connect to: admin | storefront | public | | KADUNO_API_KEY | Yes, unless KADUNO_SERVER=public | — | Your K-Shop API key or agent key | | KADUNO_API_URL | No | https://kshop.kshop01.kloner.clh.no | K-Shop API base URL (override for self-hosted / other tenants) |

CLI Flags

npx kaduno-mcp --help      # Show usage help
npx kaduno-mcp --version   # Show version

Available Servers & Tool Counts

• k-admin (~25 domain-router tools / 200+ actions) — kshop.orders, kshop.catalog, kshop.inventory, kshop.customers, kshop.platform, kshop.control, plus kshop.finance, kshop.cms, kshop.faq, kshop.reports, kshop.reach, kshop.crm, kshop.wms, kshop.purchasing, kshop.notifications, kshop.alerts, kshop.returns, kshop.work_orders, kshop.booking, and more.
• k-storefront (4 tools / 39 actions) — kshop.storefront (browse/cart/checkout/orders), kshop.storefront.b2b (company purchasing), kshop.storefront.booking.
• k-public (3 tools / 15 actions) — kshop.public.catalog, kshop.public.checkout, kshop.public.booking.

Features

• Domain routers: related actions grouped behind one tool with an action parameter — dramatically fewer tools in your agent's context window
• Guided errors: machine-readable error codes with recovery hints instead of raw exceptions
• Auto-refresh: tool catalog refreshes every 5 minutes (no restart needed for server-side tool updates)
• Offline quickstart: built-in kshop://docs/quickstart-local resource works without network
• Retry on unknown tool: automatically refreshes catalog when a tool is not found (handles server-side deploys mid-session)
• Clear error messages: auth failures, network issues, and misconfigured server selection are explained in plain language

Self-Hosted / Staging

Override the API URL for self-hosted deployments or staging environments:

{
  "mcpServers": {
    "kshop": {
      "command": "npx",
      "args": ["-y", "kaduno-mcp@latest"],
      "env": {
        "KADUNO_API_KEY": "<your-api-key>",
        "KADUNO_SERVER": "storefront",
        "KADUNO_API_URL": "https://your-store.kloner.clh.no"
      }
    }
  }
}

Troubleshooting

"Failed to connect to K-Shop <server> server" — verify the API is reachable at KADUNO_API_URL, and that KADUNO_API_KEY is valid for the selected KADUNO_SERVER.

"KADUNO_API_KEY is required when KADUNO_SERVER=admin/storefront" — the public server allows anonymous access; admin and storefront require a key.

Tool not found after a server deploy — the proxy automatically retries once after refreshing its catalog; if it still fails, restart your MCP client to force a fresh connection.

Development

git clone <repo-url>
cd publish/mcp
npm install
npm run dev    # Run from source via tsx
npm run build  # Compile with tsup

License

MIT