Claude Desktop

Option 1 — .mcpb extension bundle (recommended)

The fastest path. Claude Desktop ships with a one-click extension installer.

1. Open Claude Desktop → Settings → Extensions → drag synchronity.mcpb into the drop zone.
2. Claude prompts for two env values:
   • GATEWAY_URL — https://api.synchronity.app (or your self-hosted gateway)
   • AIT_TOKEN — see Quickstart step 2 for issuing one
3. Restart Claude Desktop. The 22 commerce tools appear under Synchronity.

Option 2 — Manual JSON config

If you prefer editing config directly, add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "synchronity": {
      "command": "npx",
      "args": ["-y", "@synchronity/mcp-server"],
      "env": {
        "GATEWAY_URL": "https://api.synchronity.app",
        "AIT_TOKEN": "<paste your AIT here>",
        "DEFAULT_SITE_ID": "<optional: pin to one site>"
      }
    }
  }
}

Restart Claude. Same outcome.

Verifying it works

In a fresh Claude conversation:

"Use Synchronity to list the stores I have connected."

Claude should call list_sites and surface the results. If you see a tool-error icon instead, check that GATEWAY_URL is reachable and AIT_TOKEN is unexpired.

Delegation in Claude

When an agent triggers a mutation that requires buyer approval (over your delegation threshold, or on a site flagged require_human_delegation), Claude renders the verification URL and user_code directly in chat. Click the URL, approve, return to the chat — Claude polls and continues automatically.