Run the store from an AI assistant

Connect an AI assistant to your store so it can answer questions and run the admin for you.

The Model Context Protocol (MCP) is how an AI client calls tools on an outside system. grav-mcp is the MCP server for Grav. It connects an assistant to your site over the REST API and picks up KahunaCart's tools automatically.

Before you begin

• Grav 2.0 or later.
• The Grav API plugin 1.0.22 or later, installed and enabled. That release added GET /mcp/tools.
• grav-mcp 0.1.2 or later.
• Node.js 18 or later on the machine running the assistant.
• An API key on an account holding api.access plus the kahunacart.* permissions the assistant needs. See REST API to generate one and Permissions and safety to choose which.

How it works

grav-mcp fetches GET /mcp/tools at startup and registers one MCP tool per entry, named kahunacart_<name>: kahunacart_list_products, kahunacart_refund_order. Calling one calls the matching API route, under the same permissions and rules as clicking the button in the admin.

Connect Claude Code

1. Open your Claude Code MCP config.
2. Add a grav server:

{
  "mcpServers": {
    "grav": {
      "command": "npx",
      "args": ["-y", "grav-mcp"],
      "env": {
        "GRAV_API_URL": "https://mysite.com/api",
        "GRAV_API_KEY": "grav_your_api_key_here"
      }
    }
  }
}

3. Restart Claude Code.

The assistant now has the core Grav tools and every KahunaCart tool your key can call.

GRAV_API_URL is your site plus /api, without the version prefix. GRAV_API_KEY is the key you generated, starting with grav_.

Other MCP clients

Any MCP client that launches a stdio server takes the same command and the same two variables: npx -y grav-mcp, with GRAV_API_URL and GRAV_API_KEY set. Claude Desktop, Cursor and VS Code each keep their MCP configuration somewhere different, so check that client's docs.

To test outside a client, run grav-mcp standalone:

GRAV_API_URL=https://mysite.com/api GRAV_API_KEY=grav_abc123 npx grav-mcp

The same settings are available as CLI flags: --url, --key, --environment, --plugin-tools, --transport and --port. For a remote deployment, use HTTP instead of stdio:

npx grav-mcp --url https://mysite.com/api --key grav_abc123 --transport http --port 3100

Check the connection

1. Ask the assistant to run discover_plugins.
2. Read the mcp_tools block in the answer. It lists the loaded tools by plugin, and kahunacart should be one of them.
3. If your client can show its tool list, look there for names starting with kahunacart_ instead.

When kahunacart is missing, read grav-mcp's stderr. A plugin-tools problem never stops it: grav-mcp prints a warning naming the cause and starts with the core Grav tools only. Troubleshooting lists the causes and fixes.

Fix the cause, then ask the assistant to run refresh_plugin_tools. No restart is needed.

What the assistant can do

KahunaCart publishes 379 tools over 415 admin routes, behind 11 permissions. An assistant calls each one by its name below with kahunacart_ in front of it.

These 36 routes are not published as tools: GET /kahunacart/admin/sections/{id}.js, GET /kahunacart/admin/widget.js, POST /kahunacart/categories/{id}/image, GET /kahunacart/config/export, GET /kahunacart/orders/{id}/receipt.html, GET /kahunacart/address-lookup, GET /kahunacart/import/runs/{id}/errors.csv, POST /kahunacart/import/uploads, POST /kahunacart/notification-channels, DELETE /kahunacart/notification-channels/{id}, PATCH /kahunacart/notification-channels/{id}, POST /kahunacart/notification-channels/{id}/test, POST /kahunacart/object-templates/preview, GET /kahunacart/previews, GET /kahunacart/previews/email/{kind}, GET /kahunacart/previews/pdf/{document}, POST /kahunacart/orders/{id}/downloads, GET /kahunacart/badge, POST /kahunacart/orders/bulk/pdf, GET /kahunacart/orders/{id}/credit-notes/{cnid}.pdf, GET /kahunacart/orders/{id}/packing-slip.pdf, GET /kahunacart/orders/{id}/refund-request/label.pdf, GET /kahunacart/orders/{id}/shipments/{sid}/packing-slip.pdf, POST /kahunacart/products/{id}/files, POST /kahunacart/products/{id}/media, POST /kahunacart/products/{id}/releases/publish, GET /kahunacart/reports/export, GET /kahunacart/reports/export.pdf, GET /kahunacart/export/catalog.yaml, GET /kahunacart/export/customers.csv, GET /kahunacart/export/products.csv, GET /kahunacart/exports/{id}/download, POST /kahunacart/restores/uploads, GET /kahunacart/tax/rates/export, POST /kahunacart/webhook-subscriptions/{id}/ping, GET /kahunacart/zones/widgets/{id}.js.

Your key's permissions decide which of these exist in a session. The routes with no tool are the multipart uploads, the CSV and PDF exports, the two admin script routes and the sidebar badge the admin shell polls for itself. Manifest version 1 does not cover them.

The Arguments column names the properties of each tool's input schema.

Six things you can ask for

Permissions and safety

Three controls govern an assistant's access to your store.

The key decides which tools exist. GET /mcp/tools leaves out every tool whose permission the key does not hold. A key with only kahunacart.reports gets no refund tool. A super admin sees everything.

Every call is checked twice. grav-mcp checks the permission before calling, and the API plugin checks it again on the route. A tool that slipped through is still refused with 403.

Annotations tell the client what a tool is. Every GET is read-only. Deletes are destructive, and so are refund_order, cancel_order and revoke_download. A client can then ask before running one.

A store with demo.readonly on refuses every write with 403 before the handler runs, whatever the key holds. Reads are never blocked.

To limit which plugins publish tools, set --plugin-tools or GRAV_MCP_PLUGIN_TOOLS. all is the default, none turns plugin tools off, and a comma-separated list of plugin slugs loads only those:

npx grav-mcp --url https://mysite.com/api --key grav_abc123 --plugin-tools kahunacart

Two conventions matter when reading the results.

Money goes in as decimal strings in the store currency ("19.99") and comes back as minor-unit integers (price_minor, total_minor, refunded_minor). Read currency_exponent from get_config to convert. See Money conventions.

attributes on a product update is a merge keyed by attribute slug. A slug you do not send keeps its value; a slug sent as null is removed. Every other list-valued field replaces its whole set.

Selling a grouped product as a set takes sell_as_set. create_product and update_product accept sell_as_set (true or false) on a grouped product or a kit. On, the product's own variant price is the bundle price of a full set of its children, and the children stay separate lines. Set the price through variants, as for any product. get_product answers set_price for these products: parts_minor, price_minor, saving_minor and sells_as_set, in the store's own currency. search_variants also takes ids, a comma-separated list such as 24,25, and answers those variants in that order instead of searching.

Add-ons

The Licenses, Subscriptions, Newsletters, Shipping, Bookings and Rentals add-ons ship their own mcp.yaml manifests. Installing one adds its tools to the same session, once the plugin is enabled and the tools are refreshed.

Licenses

The admin tools need kahunacart.licenses. Three of them call the public validation routes your software already uses, so an assistant can check a customer's key with no permission at all. What each does to a key is on Licenses.

Licenses publishes 21 tools over 32 admin routes, behind 1 permission. An assistant calls each one by its name below with kahunacart_licenses_ in front of it.

These 4 routes are not published as tools: POST /kahunacart/licenses/public/activate, POST /kahunacart/licenses/public/deactivate, GET /kahunacart/licenses/public/file, GET /kahunacart/licenses/public/release. Nor are the 7 OPTIONS preflight routes.

Subscriptions

Reads need kahunacart.subscriptions.view, writes kahunacart.subscriptions.manage. A renewal is an ordinary order, so marking one paid is kahunacart_mark_order_paid from the base plugin. What each action means is on Subscriptions.

Subscriptions publishes 17 tools over 17 admin routes, behind 2 permissions. An assistant calls each one by its name below with kahunacart_subscriptions_ in front of it.

Newsletters

Reads need kahunacart.newsletters.view, writes kahunacart.newsletters.manage. Starting, resuming or test-sending a campaign needs kahunacart.newsletters.send on top of .manage. What each action means is on Newsletters.

Newsletters publishes 77 tools over 85 admin routes, behind 3 permissions. An assistant calls each one by its name below with kahunacart_newsletters_ in front of it.

These 8 routes are not published as tools: GET /kahunacart/newsletters/campaigns/{id}/preview, GET /kahunacart/newsletters/campaigns/{id}/sends/{send}/view, POST /kahunacart/newsletters/imports, POST /kahunacart/newsletters/imports/preview, GET /kahunacart/newsletters/subscribers/export, GET /kahunacart/newsletters/labels, GET /kahunacart/newsletters/reports/{type}.csv, GET /kahunacart/newsletters/templates/{id}/preview.

Shipping

Setting up carriers, boxes and addresses needs kahunacart.shipping.manage. Quoting, buying and voiding a label needs kahunacart.shipping.labels, because it spends the store's money. Reading a label, its tracking or a packing preview needs kahunacart.orders.view. What each action does is on Shipping carriers.

Shipping publishes 27 tools over 29 admin routes, behind 3 permissions. An assistant calls each one by its name below with kahunacart_shipping_ in front of it.

These 2 routes are not published as tools: GET /kahunacart/shipping/labels/{id}/file, POST /kahunacart/shipping/public/webhook/{aggregator}/{secret}.

Bookings

Reads need kahunacart.bookings.view and changes need kahunacart.bookings.manage. "What is free on Thursday" and "book Mrs Patel in at three" are both here. What each action means is on Bookings.

Bookings publishes 52 tools over 78 admin routes, behind 2 permissions. An assistant calls each one by its name below with kahunacart_bookings_ in front of it.

These 26 routes are not published as tools: GET /kahunacart/bookings/admin-slots/{id}.js, GET /kahunacart/bookings/export, POST /kahunacart/bookings/desk/bookings, GET /kahunacart/bookings/desk/bookings/{id}, POST /kahunacart/bookings/desk/bookings/{id}/{action}, GET /kahunacart/bookings/desk/customers, POST /kahunacart/bookings/desk/customers, GET /kahunacart/bookings/desk/customers/{id}, POST /kahunacart/bookings/desk/customers/{id}, GET /kahunacart/bookings/desk/diary, GET /kahunacart/bookings/desk/me, GET /kahunacart/bookings/desk/services, GET /kahunacart/bookings/desk/slots, GET /kahunacart/bookings/public/availability, POST /kahunacart/bookings/public/book, GET /kahunacart/bookings/public/channels/{token}.ics, GET /kahunacart/bookings/public/feeds/{token}.ics, POST /kahunacart/bookings/public/holds, DELETE /kahunacart/bookings/public/holds/{id}, GET /kahunacart/bookings/public/manage/{token}, POST /kahunacart/bookings/public/manage/{token}/cancel, POST /kahunacart/bookings/public/manage/{token}/claim-offer, POST /kahunacart/bookings/public/manage/{token}/reschedule, GET /kahunacart/bookings/public/me, GET /kahunacart/bookings/public/services, GET /kahunacart/bookings/public/sessions.

Rentals

Rentals uses the Bookings permissions: kahunacart.bookings.view to read a rate card or quote a stay, kahunacart.bookings.manage to change one. Anything a guest does, such as asking what is free next August, is a Bookings tool. See Rentals.

Rentals publishes 9 tools over 9 admin routes, behind 2 permissions. An assistant calls each one by its name below with kahunacart_rentals_ in front of it.