> ## 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.

# Sync Server Skill

> Skill file for agents operating the StateSet Sync Server — tenant-scoped order, inventory and product sync across 180+ integrations, over REST, CLI or MCP.

Operate and use the StateSet Sync Server as a commerce integration platform.

## How It Works

1. Confirm configuration source: `STATESET_APP_CONFIG_JSON`, `APP_CONFIG_PATH`, or `config/app_config.json`.
2. Start the server or verify an existing instance.
3. Check health and API docs before invoking workflows.
4. Use tenant-scoped REST, CLI, or MCP calls with tenant auth.
5. For writes, use idempotency keys and explicit confirmation where the surface supports it.
6. After syncs, inspect jobs, webhook events, audit logs, and reconciliation/commerce ops views.

## Status Flows

* **Server:** configured -> starting -> healthy | degraded | failed
* **Sync Job:** queued -> running -> succeeded | retrying | failed | dead\_lettered
* **Webhook:** received -> validated -> persisted -> processed | retrying | failed
* **MCP Tool:** discovered -> validated -> confirmed -> executed -> audited

## Usage

* Local server: `cargo run` or `stateset-sync-server`
* Healthcheck: `stateset-sync-server --healthcheck`
* API docs: `GET /docs/` or `GET /api-docs/openapi.json` on your server
* REST base path: `/v1/tenants/{tenant_id}/...`
* MCP smoke test: `stateset-sync-server mcp-test --url <url> --tenant <tenant_id> --api-key <key>`
* MCP stdio: `stateset-sync-server mcp-stdio --tenant <tenant_id>`
* CLI: `stateset-sync --help`

## Permissions

* **Read:** health, docs, list/get orders, list jobs, inventory reads, plan tiers, MCP `tools/list`, MCP resources.
* **Write:** create/update orders, trigger syncs, replay webhooks, inventory reservations, custom MCP tools.
* **Admin:** platform diagnostics, tenant policy, audit logs, operator-safe dashboard routes.

Writes should include an `Idempotency-Key` header when available and should not be retried blindly after a timeout without checking job or idempotency state.

## Examples

```bash theme={null}
export APP_CONFIG_PATH=./config/app_config.json
cargo run
curl -fsS http://127.0.0.1:8080/healthz
curl -fsS -H "x-stateset-api-key: $STATESET_API_KEY" \
  http://127.0.0.1:8080/v1/tenants/acme/jobs
stateset-sync-server mcp-test --url http://127.0.0.1:8080 --tenant acme --api-key "$STATESET_API_KEY"
```

## Output

```json theme={null}
{"health":"ok","tenant":"acme","jobs":{"queued":0,"running":0,"failed":0},"mcp":{"tools":42}}
```

## Present Results to User

* Server URL, tenant ID, and config source used.
* Health/readiness result and any degraded dependency.
* Auth method used: tenant API key, JWT, CLI token, or admin key.
* For syncs: job ID, state, retry count, failures, and next inspection endpoint.
* For MCP: tool name, params, confirmation/dry-run status, and response `_meta`.
* Exact command or endpoint for the next step.

## Troubleshooting

* Config missing: set `APP_CONFIG_PATH` or `STATESET_APP_CONFIG_JSON`.
* Auth rejected: verify tenant ID, `x-stateset-api-key`, JWT claims, or CLI token.
* Metrics protected: set `STATESET_METRICS_AUTH_TOKEN` and pass `Authorization: Bearer`.
* Sync stuck: inspect `/v1/tenants/{tenant_id}/jobs`, DLQ, and webhook events.
* Shopify inventory mismatch: verify the fulfillment integration's `shopify_inventory_location_id` and the Shopify locations it maps to.
* MCP mismatch: run `mcp-test`, then compare tool schemas from `tools/list`.

## Error Codes

* `tenant_not_found`: Tenant ID is not configured.
* `unauthorized`: Missing or invalid tenant authentication.
* `missing_integration`: Tenant lacks the requested connector.
* `rate_limit_exceeded`: Retry after the provided `Retry-After` value.
* `idempotency_conflict`: Same key was reused with a different request fingerprint.

## Further reading

* [Sync Server MCP](/stateset-sync-mcp) — the 186-tool registry and four transports
* [Sync Server connectors](/stateset-sync-server-connectors)
* [Sync Server troubleshooting](/stateset-sync-server-troubleshooting)