The fastest useful start
The first-operation walkthrough supports both people and agents:- Run its setup program to create the local order and stock records.
- Run its inspection program to verify the result yourself.
- Add the generated
stateset-commerceentry to your MCP host and reconnect it. - Paste the generated
agent-task.txtinto the conversation. - Compare the agent’s tool results with the independent inspection output.
pending and 25.00 USD, reads stock
as 10 on hand / 2 allocated / 8 available, and explains why another nine-unit request cannot be
fully reserved. The host must show actual tool calls. No business write is needed for this task.
The local engine needs Node.js 20.20.0+ and npm 10+. The MCP host supplies its own model
connection; a hosted StateSet API key is not required for this local database example.
Start here: pick one server
For an existing operation, connect the service that owns the needed capability. Credentials, transports, and workspace selection are specific to each server.
Use the MCP directory for the complete connection catalog. If your agent runtime
calls HTTP directly, use the API directory for the host, header,
key scope, and endpoint contract. MCP and REST are alternative interfaces; do not translate
method names or request fields between them by guesswork.
Hand the agent an explicit operation
Replace the bracketed fields in this task brief before using it:Use this operating procedure
1. Discover the actual contract
Read the relevant guide and inspect the host’s exposed tools or MCPtools/list response.
Use the returned tool name and input schema. The installed version and selected profile decide
which tools are available; a tool mentioned in a different release may not be present.
For iCommerce CLI 1.35.1, the first read can use get_order with identifier and get_stock
with sku. Confirm these in your host. Their results wrap records in order and stock and
include a success flag; inspect that flag as well as the returned data.
2. Read the inputs from the selected system
Use actual IDs supplied by the operator or returned from tools. Check the selected database or tenant before interpreting an empty result. Distinguish missing data from zero stock, an empty inbox, or a completed workflow.3. Apply the configured permissions and business rules
Scope tools and write permissions in the server configuration. In the local CLI 1.35.1 starter,--profile core selects domains and omitting --apply keeps writes preview-only. Profiles and
write permissions are separate settings. Direct embedded-library writes execute immediately.
When your operation uses a decision gate, follow the
verified-decision workflow with the required facts and
proof checks. A decision that permits an action is not evidence that the action was executed.
An NSR connection is a separate integration; adding it does not automatically gate another
server’s writes.
4. Execute only the intended operation
Preserve operation IDs and original retry keys. Check idempotency support per endpoint or tool; a reference ID or an arbitrary header is not automatically a replay guarantee. After a timeout, reconcile the original outcome before issuing another write. A409 may mean
an in-flight request, a changed payload, or a limit; a 5xx does not prove that nothing happened.
Use the error-handling guide rather than a generic retry loop.
5. Verify the outcome in the system of record
Read back the record or inspect the documented terminal workflow state. Where an external provider is involved, verify its result separately. A local payment marked completed does not charge a card, and an order status change does not purchase a label or send a customer message. For multi-step operations, retain the links between the local record, workflow ID, decision, and provider result. The integration test plan explains what to assert at each boundary.Scope before you connect
Start with the domains your task uses. For iCommerce, the MCP setup guide explains thecore, operations, finance, agents, and all profiles. Inspect available tools after
changing a profile.
Before enabling writes in CLI 1.35.1, configure its trusted policy, principal, and store ID as
described in that guide. A prompt requesting permission is not a substitute for server-side
configuration. Choose the allowed operations according to your own workflow and authorization.
Reading these docs directly
The machine-readable index links to topic indexes and Markdown pages. Fetch the relevant index, then only the task guide and reference pages you need. For this onboarding path, start with:- First operation: fixture, generated connection configuration, and verification.
- iCommerce MCP: transport, profiles, and write configuration.
- API directory: service-specific hosts and credentials.
- Error contracts: fields to inspect on failures.
Skills: the layer above tools
Tools expose operations. Skills provide task procedures and domain context. Use the skills directory to find the relevant procedure and the iCommerce skills guide for installation details. Check the procedure against the installed server’s tool schemas before execution.Expand to a complete workflow
For existing business data, use Connect Your Operation. It provides service-specific readiness checks and a shared task brief for operators and agents.
If setup fails, share the selected service, package/runtime version, failed operation, and
redacted error using the support checklist.