Claude

Claude Code: plugin marketplace

If you use Claude Code (the CLI / IDE extension), install Synchronity as a plugin from the public marketplace:

/plugin marketplace add themewireco/synchronity
/plugin install synchronity@synchronity

That's the whole setup. The plugin bundles the synchronity-commerce skill and runs the MCP server locally via npx @synchronity/mcp-server against the hosted gateway (https://api.synchronity.app). Nothing to clone, build, or configure. Then just shop:

"Find me a birthday cake from my connected stores."

The marketplace tracks the repo's main branch, so /plugin marketplace update pulls future updates. (Requires Node/npx available on your machine.)

The rest of this page covers 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. That's it — no configuration to enter. The bundle ships preconfigured for the hosted gateway (https://api.synchronity.app) and authenticates automatically (it registers an agent identity with the gateway on first run — no token to paste).
3. Restart Claude Desktop. The 26 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. Every env var is optional — GATEWAY_URL defaults to the hosted gateway and the server auto-registers its own identity, so you only need to override these to point at a self-hosted gateway or pin a default site:

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

Restart Claude. Same outcome. (Advanced: set AIT_TOKEN to pin a specific pre-issued Agent Identity Token instead of letting the server auto-register.)

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 the gateway (https://api.synchronity.app, or your GATEWAY_URL override) is reachable.

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.