Sync Server MCP

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.

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.

Sync Server: What's New Sync Server API Basics

Get started

Platform

StateSet One

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce

StateSet Commerce

StateSet EDI

StateSet Mail

StateSet Voice

StateSet NSR

AI Agents

StateSet Sandbox

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Tools

Sync Server MCP

Sync Server MCP

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

​Sync Server MCP

​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

Sync Server MCP

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