Sync Server Skill

​

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.

​

Examples

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

{"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 — the 186-tool registry and four transports
• Sync Server connectors
• Sync Server troubleshooting