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

> Connect an MCP host to a Sync Server tenant — four transports, per-tenant policy, and admin controls.

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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:

```bash theme={null}
# 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"
```

<Note>
  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.
</Note>

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

## Related

* [Sync Server API Basics](/stateset-sync-server-api-basics)
* [Sync Server: What's New](/stateset-sync-server-whats-new)
* [All MCP servers](/mcp-servers)