> ## Documentation Index > Fetch the complete documentation index at: https://docs.stateset.com/llms.txt > Use this file to discover all available pages before exploring further. # Getting started for AI agents > The entry point for an AI agent operating StateSet — which MCP server to connect, what it can do, and the rules that keep an agent from doing damage. # 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](/mcp-servers). ## Start here: pick one server Do not connect all ten. Pick the one that matches the job. | If the job is… | Connect | Tools | | ------------------------------------------------------------ | ----------------------------------------------------------------- | ------- | | **Run a store** — orders, inventory, fulfillment, accounting | [`stateset-commerce`](/stateset-icommerce/stateset-icommerce-mcp) | **719** | | **Decide whether an action is allowed** | [`stateset-nsr-mcp`](/stateset-nsr-mcp) | 14 | | **Trade documents with partners** — POs, ASNs, invoices | [`@stateset/edi-mcp`](/stateset-edi/mcp-server) | 117 | | **Answer the phone** | [`@stateset/voice-mcp-server`](/stateset-voice/mcp-server) | 24 | | **Send email, work an inbox** | [`stateset-mail-mcp`](/stateset-mail/mcp-server) | 26 | | **Operate software that has no API** | [`@stateset/computer-use-agent-mcp`](/computer-use-mcp) | 9 | | **Build or tune a CX agent** | [`responsecx`](/stateset-response/response-mcp) | — | | **Change automation config** | [`stateset-config-connector`](/next-temporal/mcp-connector) | 7 | | **Sync across 180+ integrations** | [Sync Server](/stateset-sync-mcp) | — | | **Drive Shopify, Gorgias, Recharge** | [Sandbox servers](/stateset-sandbox/stateset-sandbox-mcp) | 40+ | **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](#scope-before-you-connect)). ## 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. ```json theme={null} { "mcpServers": { "stateset-commerce": { "command": "npx", "args": ["-y", "@stateset/cli@latest", "stateset-mcp-events"], "env": { "DB_PATH": "./store.db" } } } } ``` 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**. ```bash theme={null} curl -X POST https://api.stateset.com/api/v1/orders \ -H "Authorization: Bearer $STATESET_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'content-type: application/json' \ -d '{ "customer_id": "cus_1042", "line_items": [{ "sku": "SHOE-RED-10", "quantity": 1 }] }' ``` 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](/api-reference/errors), 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: | Reversible | Effectively irreversible | | ------------------------------------------ | ---------------------------------------------- | | Create a draft, update a field, add a note | **Issuing a refund** | | Cancel an unfulfilled order | **Completing a fulfillment / shipping** | | Adjust a reservation | **Posting a journal entry to a closed period** | | Change a rule | **Sending an email or placing a call** | | | **Voiding an invoice** | 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](/stateset-nsr-decisions) replaces that reasoning with a **verified decision**: a symbolic rule engine returns `approved`, `denied`, or `refused`, with the rules it cited as proof. ```bash theme={null} curl -X POST https://api.stateset.com/v1/decisions \ -H "Authorization: Bearer $STATESET_API_KEY" \ -H 'content-type: application/json' \ -d '{ "query": "refund_allowed(order_941)", "context": { "order_id": "941" } }' ``` 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](/stateset-nsr-formal-verification), 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: | Class | Meaning | Retry? | | ----------------------------- | ------------------------------ | -------------------------------------------- | | `400` / `INVALID_ARGUMENT` | The request is malformed | **No** — fix it | | `401` / `403` | Credential or scope problem | **No** — a human must act | | `404` / `NOT_FOUND` | It does not exist | **No** | | `409` / `FAILED_PRECONDITION` | Not valid in the current state | **No** — change state first | | `402` | Metering or quota | **No** — see [billing](/stateset-billing) | | `429` | Rate limited | **Yes** — honour `RateLimit-Reset` | | `5xx` / `UNAVAILABLE` | Transient | **Yes**, with backoff and an idempotency key | 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](/api-reference/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: ```bash theme={null} npm install -g @stateset/icommerce-skills icommerce-skills list icommerce-skills install ``` | Area | Skills | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Orders and customers** | `commerce-orders`, `commerce-checkout`, `commerce-customers`, `commerce-customer-service`, `commerce-subscriptions`, `commerce-promotions`, `commerce-storefront` | | **Inventory and warehouse** | `commerce-inventory`, `commerce-warehouse`, `commerce-lots-and-serials`, `commerce-backorders` | | **Fulfillment** | `commerce-fulfillment`, `commerce-shipments`, `commerce-receiving`, `commerce-returns`, `commerce-warranties` | | **Manufacturing** | `commerce-manufacturing`, `commerce-quality` | | **Financials** | `commerce-general-ledger`, `commerce-accounts-payable`, `commerce-accounts-receivable`, `commerce-invoices`, `commerce-payments`, `commerce-cost-accounting`, `commerce-credit`, `commerce-tax`, `commerce-currency` | | **Suppliers** | `commerce-suppliers` | | **Platform** | `commerce-engine-setup`, `commerce-mcp-tools`, `commerce-events`, `commerce-sync`, `commerce-products`, `commerce-analytics`, `commerce-vector-search`, `commerce-embedded-sdk`, `commerce-autonomous-engine`, `commerce-autonomous-runbook` | 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: | Skill | Fetch | | -------------------------------------- | ------------------------------------------------------- | | [iCommerce](/stateset-icommerce-skill) | `https://docs.stateset.com/stateset-icommerce-skill.md` | | [Sandbox](/stateset-sandbox-skill) | `https://docs.stateset.com/stateset-sandbox-skill.md` | ## Reading these docs directly If you would rather read than install, this site is already machine-readable — no scraping and no HTML parsing. | URL | What it is | | ----------------------------------------- | ------------------------------------------------------------ | | `https://docs.stateset.com/llms.txt` | Every page in the site, as a linked index | | `https://docs.stateset.com/llms-full.txt` | The entire documentation as one document | | any page + `.md` | That page as raw Markdown, e.g. `/stateset-nsr-decisions.md` | 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](/mcp-servers). ## What is behind the tools MCP is a wrapper. If you need the underlying surface: | | | | ------------------------------------------------ | -------------------------------------------------- | | [Commerce API](/api-reference/commerce/overview) | 432 operations — orders through the general ledger | | [StateSet One API](/api-reference/overview) | The platform API | | [gRPC](/api-reference/grpc-framework) | 17 services, for service-to-service calls | | [Decisions](/stateset-nsr-decisions) | The verified decision gate | | [Webhooks](/api-reference/webhooks) | React to events instead of polling | 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 `stateset-commerce` with `DB_PATH` pointing at a duplicate. List orders. Look up inventory. Confirm the data is what you expect. Create a draft. Add a note. Verify it landed, and undo it. Route refunds, cancellations, and sends through [decisions](/stateset-nsr-decisions). Add a second server, or unlock write tools, one domain at a time. ## Related * [MCP Servers](/mcp-servers) — all ten, with transports and per-server config * [Decision gate](/stateset-nsr-decisions) — verified authorization * [Formal verification](/stateset-nsr-formal-verification) — what is actually proven * [Why StateSet](/why-stateset) — what makes this different from an API with an SDK * [Errors](/api-reference/errors) · [Rate limiting](/api-reference/rate-limiting)