StateSet API Docs

The Sync Server speaks MCP (JSON-RPC 2.0, protocol version 2025-03-26) so an agent can drive order, inventory, product, and returns operations across 180+ integrations for a given tenant.

What it exposes

The registry holds 186 general-purpose tools across 29 categories, plus a small number of tenant-specific operations built for individual accounts.

Category	Tools	Category	Tools
Monitoring	21	Reconciliation	8
Inventory	16	Analytics	8
Shopify	14	Connectors	7
NetSuite	11	Schedules	6
Webhooks	10	Dead-letter queue	6
Jobs	10	Walmart	5
Orders	9	Tracking	5
Flows	9	Returns	5
Billing	9	Sync	3
Tenant	8	Agent	3

The remainder are one or two tools each for Amazon, eBay, Etsy, TikTok, MercadoLibre, Shopware, WooCommerce, products, and audit.

tools/list does not return all of them. It defaults to availableOnly, hiding any tool whose integration is not configured for the tenant, and the read-only mode and per-tenant blocklist below narrow it further. Count against your own tenant rather than against this table.

Transports

Four, depending on where the agent runs:

Transport	Endpoint	Auth	Use for
HTTP	`POST /v1/tenants/{tenant_id}/mcp`	`x-stateset-api-key` or `Bearer`	Server-to-server, hosted AI, back-end agents
Streamable HTTP / SSE	`GET /v1/tenants/{tenant_id}/mcp/sse`	Same	Server-push notifications — progress, resource updates
stdio	`stateset-sync-server mcp-stdio --tenant <id>`	Env (`APP_CONFIG_PATH`, `DATABASE_URL`)	Desktop clients launching the binary as a child process
Multi-tenant HTTP	`POST /v1/mcp`	`x-stateset-admin-key`	One operator connection addressing any loaded tenant

The multi-tenant transport takes the tenant per request via params._meta.tenant.

Connect

Remote (recommended for a hosted server)

{
  "mcpServers": {
    "stateset-sync": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.sync.stateset.com/v1/tenants/<tenant_id>/mcp",
        "--header", "x-stateset-api-key: ss_sync_..."
      ]
    }
  }
}

stdio (local binary)

{
  "mcpServers": {
    "stateset-sync": {
      "command": "stateset-sync-server",
      "args": ["mcp-stdio", "--tenant", "acme"],
      "env": { "APP_CONFIG_PATH": "…", "DATABASE_URL": "…" }
    }
  }
}

Both expose the same tool surface — pick based on where the agent runs, not on capability.

Safety controls

The Sync Server has the most developed per-tenant guardrails of any StateSet MCP server, because its tools reach live commerce platforms.

Read-only mode

Freeze a tenant so every mutating tool is refused while reads keep working. Useful during an incident.

Tool blocklist

Finer-grained than read-only — disable specific tools for a specific tenant and leave the rest available:

# Disable cancel_order for tenant 'acme'
curl -X POST "https://sync.example.com/v1/admin/tenants/acme/disabled-tools/cancel_order" \
     -H "x-stateset-admin-key: $ADMIN_KEY"

# List what's blocked
curl https://sync.example.com/v1/admin/tenants/acme/disabled-tools \
     -H "x-stateset-admin-key: $ADMIN_KEY"
# → { "tools": ["cancel_order", "create_order"], "count": 2 }

# Re-enable
curl -X DELETE "https://sync.example.com/v1/admin/tenants/acme/disabled-tools/cancel_order" \
     -H "x-stateset-admin-key: $ADMIN_KEY"

Both read-only mode and the blocklist are DB-persisted (mcp_tenant_policy) and rehydrate into the in-memory registries at startup — so a pod restart mid-incident cannot silently unfreeze a tenant or re-enable a blocked tool.

Result cache

An opt-in per-tenant cache on tool results, for read-heavy agent loops.

Operations

Surface	Purpose
Runtime inspection (admin)	What’s loaded and active per tenant
Runtime diagnostics	Health of the MCP surface itself
SSE subscriptions	Progress and resource-update notifications

Observability config ships with the repo — docs/observability/mcp-alerts.yaml and mcp-dashboard.json.

claude.ai custom connector

The server supports claude.ai Custom Connectors over OAuth 2.1, with a documented issuer surface and a dashboard handoff contract. This is the path for connecting a tenant to claude.ai without distributing an API key.

Last modified on August 29, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Sync Server MCP

What it exposes

Transports

Connect

Remote (recommended for a hosted server)

stdio (local binary)

Safety controls

Read-only mode

Tool blocklist

Result cache

Operations

claude.ai custom connector

​What it exposes

​Transports

​Connect

​Remote (recommended for a hosted server)

​stdio (local binary)

​Safety controls

​Read-only mode

​Tool blocklist

​Result cache

​Operations

​claude.ai custom connector

​Related

What it exposes

Transports

Connect

Remote (recommended for a hosted server)

stdio (local binary)

Safety controls

Read-only mode

Tool blocklist

Result cache

Operations

claude.ai custom connector

Related