Skip to main content

​
Getting started for AI agents

If you are an AI agent — or you are wiring one up — this is the map. StateSet is built to be operated by agents rather than only by people, and MCP is the primary interface. There are 10 MCP servers exposing roughly 950 tools across commerce, EDI, voice, mail, decisions, automation, and computer use. Read this page first. It tells you which server to connect, what you can do with it, and the four rules that separate a useful agent from an expensive one.
Human wiring this up? Every config below goes in your MCP host’s config file — claude_desktop_config.json for Claude Desktop, or claude mcp add for Claude Code. Full per-server detail is in MCP Servers.

​
Start here: pick one server

Do not connect all ten. Pick the one that matches the job.
More tools is not better. Connecting several servers at once puts hundreds of tool definitions in your context, which degrades selection accuracy — the model picks the wrong tool more often as the list grows. Connect one server, or scope a large one down (see Scoping).

​
The fastest useful start

stateset-commerce is the broadest surface and needs no server running — the commerce engine is embedded and operates directly against a SQLite file.
Point DB_PATH at a copy of your database the first time. Of those 719 tools, 287 write, 47 administer, and 21 delete. A mistaken call is much easier to live with when the original file is untouched.
Then ask for something read-only first — “list the last 10 orders” — and confirm you get real data before you let the agent write anything.

​
The four rules

These are what actually matter. Everything else is detail.

​
1. Send an idempotency key on every write

An agent retries. That is its nature — a timeout, a rate limit, a re-plan after an ambiguous response. Without an idempotency key a retry creates a second order.
Reuse the same key for retries of the same intent; generate a new one for a genuinely new action.
A timeout does not mean the write failed. The server may have committed and then failed to respond in time. Never resolve a timeout by repeating the call without a key — check first, or send the original key and let the server replay its own answer.

​
2. Know which calls cannot be undone

Reads are free. Writes are not, and a few are irreversible: Treat the right column as requiring an explicit decision, not an inference from context. Which brings us to the rule that matters most.

​
3. Do not decide authorization yourself — ask the gate

This is the part of StateSet built specifically because agents are persuasive and wrong. An agent asked “can I refund this $400 order?” will reason its way to an answer, and a customer who argues will move that answer. The decision gate replaces that reasoning with a verified decision: a symbolic rule engine returns approved, denied, or refused, with the rules it cited as proof.
Three properties worth relying on:
  • Refuse by default. If nothing proves the action is permitted, the answer is refused — not a guess, and not a best effort.
  • Deny wins. A firing denial cannot be diluted by adding permissions beside it.
  • It degrades into refusing. Under budget exhaustion it can lose conclusions but never gain a false one.
Those properties are machine-checked in Lean 4, with differential tests binding the proofs to the shipped code.
The correct pattern is: gate decides, agent executes. Ask the gate whether the action is allowed, then call the tool that performs it. Do not ask the model to weigh the policy — ask the gate, and let the model handle the parts that need language.

​
4. Read the error, do not retry blindly

Errors tell you whether retrying can possibly help: Branch on the code field, never on message — messages get reworded. Log request_id; it is what support needs to trace one call. Full catalogue in Errors.

​
Skills: the layer above tools

MCP gives an agent tools. Skills give it procedure — the ordered steps, the field names, and the gotchas for a specific job, written for an agent to read. The distinction matters. An agent with 719 commerce tools and no skill knows every call and no workflow: it can create a cart, but not that you set the shipping address before fetching rates, and complete checkout only after a payment method exists. A skill encodes that sequence. 38 public skills ship for iCommerce, one per domain:
Each skill is a SKILL.md with a name, a description saying when to use it, and reference files alongside. Hosts that support skills load the description up front and pull the body only when it becomes relevant, so installing all 38 does not flood your context the way connecting several MCP servers does.
Install skills broadly, connect MCP servers narrowly. They behave oppositely: a skill costs you one line of description until it is needed, while every MCP tool definition sits in context from the moment you connect. Skills are how you get coverage without paying for it.
Two skills are also published as readable documents, for hosts that prefer fetching over installing:

​
Reading these docs directly

If you would rather read than install, this site is already machine-readable — no scraping and no HTML parsing. Both index files are generated automatically and stay current, and are also served from /.well-known/llms.txt and /.well-known/llms-full.txt.
Start from llms.txt rather than llms-full.txt. The index costs little, and it lets you fetch only the pages that turn out to matter — pulling the whole corpus spends most of your context on domains you will never touch.

​
Scope before you connect

A large server can be narrowed, which improves both safety and tool-selection accuracy.
  • Read-only first. Expose only read tools until the agent has demonstrably correct behaviour.
  • Restrict by domain. An agent handling returns does not need the general ledger.
  • Put the destructive tools behind a review step, not behind a prompt instruction. A prompt is a request; a review gate is a control.
Per-server scoping is documented on each server’s page — start from MCP Servers.

​
What is behind the tools

MCP is a wrapper. If you need the underlying surface: Both REST surfaces are generated from OpenAPI specs, so the documented shapes are the shapes the code serves.
The commerce API is mounted at /api/v1, not /v1. A request to /v1/orders returns 404. The decisions, agents, and ResponseCX surfaces do use /v1. Copy the base URL from the page you are reading rather than assuming one prefix throughout.

​
A sensible first hour

1

Connect one server against a copy of your data

stateset-commerce with DB_PATH pointing at a duplicate.
2

Do only reads

List orders. Look up inventory. Confirm the data is what you expect.
3

Write one reversible thing

Create a draft. Add a note. Verify it landed, and undo it.
4

Wire the gate before anything irreversible

Route refunds, cancellations, and sends through decisions.
5

Then widen

Add a second server, or unlock write tools, one domain at a time.