Skip to main content
The iCommerce MCP server exposes the embedded engine as tools for an MCP host. The host starts stateset-mcp as a local process; the server reads your SQLite database directly. This guide uses the stdio server from @stateset/cli 1.35.1 with the core tool profile and writes disabled. A model provider is managed by your MCP host; this connection does not need a hosted StateSet API key.

​
Before you connect

For a new project, Your First Operation generates a database, an MCP configuration containing its absolute path, and a task prompt with the actual order ID. Use that walkthrough to avoid manually copying the example path below.
  1. Install Node.js 20.20.0+ and npm 10+ on the machine running your MCP host.
  2. Complete the iCommerce quickstart to create quickstart.db with an example customer and order.
  3. Find the database’s absolute path. Desktop applications may start subprocesses from a different directory than your terminal.
Check that npm can find the server command:
Success: the help text lists --db, --profile, and --apply. The -p option selects the package; stateset-mcp selects its MCP executable.

​
Connect

Add this entry to your host’s MCP configuration. Replace the database path with the absolute path to the file from the quickstart, then restart or reconnect the server in your host.
On Windows, use a path such as C:/Users/you/stateset-quickstart/quickstart.db inside the JSON. If your host cannot locate npx, configure the executable path using that host’s process-launch settings. Its environment may differ from your terminal.
Choose the database deliberately. A valid new path can open a new, empty database, so a successful connection alone does not prove that the agent is reading the file you intended.

​
Verify the first read

Ask your agent:
Success: the host shows a tool call, and the result includes the order ID saved in order-id.txt, status pending, and total 25.00 USD. If you ran the quickstart more than once, there may be several matching orders. Cross-check independently from the quickstart directory:
If the agent responds without a tool call, check that the host enabled the server. If the tool returns an empty list, check the database path before creating more data.

​
Scope the tool catalog

The tool list depends on the installed release and selected profile. Inspect your host’s tool list, or the MCP tools/list result, to see what is actually available. Set --profile in the configuration above. --domains adds named domains to a profile; it does not subtract tools from it. Profiles choose which tools are exposed, while write permissions are configured separately.

​
Permission profile

Without --apply, write tools are preview-only: they describe the intended operation instead of mutating commerce data. Read tools remain available. Version 1.35.1 requires trusted kernel configuration when enabling --apply: a policy file, a principal file and a store ID. These are operator-owned inputs, separate from model tool arguments. Adding --apply alone produces a configuration error; keep the read-only setup above while following the CLI reference and your installed server’s --help for the write configuration.
This preview behavior belongs to the MCP server. Direct calls to the embedded JavaScript library, such as commerce.orders.createExact, execute their writes immediately.

​
Troubleshooting

​
Money values

Keep monetary values as decimal strings. An order total returned by the embedded binding is totalAmountExact; line items use unitPriceExact and totalExact. MCP tools define their own response schemas, so read the tool’s output rather than assuming every layer uses the same field names. See money precision.

​
Maintenance and recovery

Before connecting an existing store, review backup and restore. Use a test database while developing your agent’s workflow, and inspect its tool calls alongside the resulting commerce records.
Last modified on September 20, 2026