Run the store from an AI assistant

This page is for two readers: the merchant who would rather ask an assistant "which products are low on stock?" than click through the admin, and the developer wiring KahunaCart into an AI workflow or an agent of their own.

The Model Context Protocol (MCP) is the standard an AI client uses to call tools on an outside system. grav-mcp is the MCP server for Grav: it connects an assistant to a Grav site over the REST API, and it picks up the 92 KahunaCart tools automatically once your store is reachable.

Before you begin

• Grav 2.0 or later.
• The Grav API plugin 1.0.22 or later, installed and enabled. GET /mcp/tools arrived in 1.0.22.
• grav-mcp 0.1.2 or later.
• Node.js 18 or later on the machine running the assistant.
• An API key belonging to a user who holds api.access plus the kahunacart.* permissions you want the assistant to have. See REST API for generating one, and Permissions and safety for choosing which.

How it works

KahunaCart ships an mcp.yaml manifest in its plugin root that describes its admin routes as tools. The API plugin serves the union of every enabled plugin's manifest at GET /mcp/tools, filtered to the tools your API key is allowed to call. grav-mcp fetches that list at startup and registers one MCP tool per entry, named kahunacart_<name> — kahunacart_list_products, kahunacart_refund_order. When the assistant calls one, grav-mcp calls the matching API route, and the same permissions and the same rules apply as when a person clicks 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 the API plugin's base — 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 environment variables. Point it at npx -y grav-mcp with GRAV_API_URL and GRAV_API_KEY set, and consult that client's own documentation for where its MCP configuration lives — Claude Desktop, Cursor and VS Code each keep it somewhere different.

grav-mcp also runs standalone, which is how you test it outside a client:

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, run it over 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 grouped by plugin, and kahunacart should be one of them.
3. If your client can show its tool list, look for names starting with kahunacart_ instead.

When kahunacart is not there, check these in order:

• A warning on grav-mcp's stderr. grav-mcp never fails on a plugin-tools problem; it prints a warning and starts with the core Grav tools only. The warning names the cause.
• The API plugin's version. A 404 from /mcp/tools means an API plugin older than 1.0.22.
• The key's permissions. The key needs api.access before any KahunaCart permission is consulted, and it only sees tools whose permission it holds.
• The plugin. Only enabled plugins are read, so a disabled KahunaCart contributes nothing.

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

What the assistant can do

KahunaCart's manifest publishes 92 tools. Which of them exist in your session depends on your key's permissions.

A few routes the admin uses are not published as tools. File, image and category-picture uploads and the release publish route are multipart, which manifest version 1 does not cover. The CSV and PDF report exports are not JSON. The sidebar badge and the two admin script routes are left out as well. Every other JSON route the admin calls is here.

Products and variants

kahunacart.products.manage. 18 tools.

Options

kahunacart.products.manage. 9 tools.

Categories

kahunacart.settings. 7 tools.

Tags

kahunacart.settings. 4 tools.

Attributes

kahunacart.products.manage. 6 tools.

Tax

kahunacart.settings. 5 tools.

Shipping

kahunacart.settings. 4 tools.

Coupons

kahunacart.settings. 4 tools.

Sales

kahunacart.sales.manage. 5 tools.

Reports

kahunacart.reports. 6 tools, all read-only.

All but report_low_stock take from and to as YYYY-MM-DD, and default to the last 30 days.

Orders

kahunacart.orders.view to read, kahunacart.orders.manage to act, kahunacart.orders.refund to refund. 8 tools.

Downloads

kahunacart.orders.view to read, kahunacart.orders.manage to revoke. 2 tools.

Customers

kahunacart.customers.view to read, kahunacart.customers.manage to act. 5 tools.

Webhook log

kahunacart.settings. 2 tools, both read-only.

Providers

kahunacart.settings. 5 tools.

Config and admin

kahunacart.orders.view. 2 tools, both read-only.

Six things you can ask for

Permissions and safety

Three things stand between an assistant and your store.

The key decides which tools exist. GET /mcp/tools leaves out every tool whose permission the calling key does not hold, so a key with only kahunacart.reports produces a session where the refund tool is not present at all. A super admin sees everything.

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

Annotations tell the client what a tool is. Every GET is marked read-only. Deletes are marked destructive, and so are refund_order, cancel_order and revoke_download. An MCP client that asks before running destructive tools has what it needs to ask.

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

To limit which plugins publish tools at all, 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 you read what the assistant reports back. 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. And attributes on a product update is a merge keyed by attribute slug: a slug you do not send keeps its value, and a slug sent as null removes it. Every other list-valued field replaces its whole set. See Money conventions.

Add-ons

The Licenses and Subscriptions add-ons ship their own mcp.yaml manifests, so installing either one adds its tools to the same session. Both appear the moment the plugin is enabled and the tools are refreshed.

Licenses

Licenses publishes 20 tools under the kahunacart_licenses_ prefix. The admin tools need the kahunacart.licenses permission. The last three call the public validation routes your software already uses, so an assistant can check a customer's key without a permission of its own.

Subscriptions

Subscriptions publishes 17 tools under the kahunacart_subscriptions_ prefix. Reads need kahunacart.subscriptions.view; writes need kahunacart.subscriptions.manage. A renewal is an ordinary order, so marking one paid is kahunacart_mark_order_paid from the base plugin.

Refresh after installing a plugin

Install or enable a plugin while the assistant is connected, then ask it to run refresh_plugin_tools. The tool re-reads every manifest and reconciles the tool list in place: new tools are added, changed ones are updated, and tools whose plugin was disabled or removed are dropped. It reports added, updated, removed and any manifest warnings, and the MCP client is told the tool list changed.

No restart of grav-mcp or your editor is involved. refresh_plugin_tools needs api.access and nothing more.

Write tools for your own plugin

Any Grav plugin can publish its own routes the same way. Drop an mcp.yaml in the plugin root, beside blueprints.yaml and permissions.yaml, and describe each route: a name, a description written for the model, the method and path, the permission the route enforces, and a JSON Schema for the arguments. The API plugin serves it and grav-mcp registers it, with no code written on either side.

version: 1
prefix: kahunacart          # optional; defaults to the plugin slug. Tool name = "{prefix}_{name}"
tools:
  - name: list_products
    title: List products
    description: >
      List catalog products with paging, search and status filters. Returns product rows with their
      variants and attributes. Use get_product for one product with everything on it.
    method: GET
    path: /kahunacart/products
    permission: kahunacart.products.manage
    annotations:
      readOnly: true
    input:
      type: object
      properties:
        q: { type: string, description: "Search title, slug or SKU" }
        status: { type: string, enum: [draft, published, archived] }
        page: { type: integer, minimum: 1, default: 1 }
        per_page: { type: integer, minimum: 1, maximum: 100, default: 20 }

  - name: update_product
    title: Update a product
    description: Change one or more fields of a product. Only the fields sent are changed.
    method: PATCH
    path: /kahunacart/products/{id}
    permission: kahunacart.products.manage
    annotations:
      idempotent: true
    input:
      type: object
      required: [id]
      properties:
        id: { type: integer, description: "Product id" }
        title: { type: string }
        status: { type: string, enum: [draft, published, archived] }

Annotations default by method: GET is read-only and idempotent, DELETE is destructive and idempotent, PUT and PATCH are idempotent, and POST is none of them. Setting a key overrides that one default. Only JSON bodies are supported; leave multipart routes out.

If your tool list depends on data rather than a file, add entries in code instead. The API plugin fires onApiMcpTools with an McpToolCollector under $event['tools'], and $event['tools']->add('<your-slug>', [...]) takes the same fields a manifest entry does. Manifest files are read first, so a name your own mcp.yaml already claimed wins.

The full format, the JSON Schema subset a manifest may use, and what GET /mcp/tools returns are documented in the API plugin README. A typo costs you that one tool, never the rest of the file: the endpoint reports it under warnings.

Troubleshooting

Related

• REST API
• Orders and the admin
• Products and catalog
• Licenses
• Subscriptions
• grav-mcp
• Grav API plugin