Solid Commerce Docs

Agent builder quickstart

Value: Give Claude, ChatGPT, Gemini — or any MCP-aware agent — safe, task-shaped tools that turn natural language into real Solid Commerce work: list products, check pending shipments, run sales reports, reprice listings. Reads run instantly; writes always confirm first.

Choose this if: You want an AI assistant to operate your store, not just answer questions about it.

Two ways to connect

| | Local (stdio) | Hosted (remote) | |---|---|---| | Best for | Claude Desktop, Claude Code, Codex / Gemini / Grok CLI, custom agents | Claude.ai, ChatGPT, Gemini app | | Runs | on your machine (npx) | our servers | | Auth | an API key you mint once | OAuth — you just log in | | Endpoint | npx -y @solidcommerce/mcp-server@alpha | https://mcp.solidcommerce.com/mcp |

Local gives you a key you control and works everywhere today. Hosted needs no install at all — each teammate logs in with their own Solid Commerce account.

Step 1 — Mint an API key (local path only)

  1. Sign in to your workspace and open Developer → API keys → New (the /developer/keys page).

  2. Pick the smallest scope set your agent needs. A good starting set for a read-mostly assistant:

    catalog:products:read   orders:orders:read      orders:shipments:read
reports:sales:read      reports:shipments:read  inventory:inventory_items:read

  3. Copy the key once — the secret is never shown again. It looks like ab12cd34_R8fK… (an 8-character prefix, an underscore, then the secret).

Lost a key? Revoke it and mint a new one — rotation is one click on the same page, and the audit log shows every call a key made.

Step 2 — Connect your client

Claude Desktop

Edit the Claude Desktop config file:

{
  "mcpServers": {
    "solidcommerce": {
      "command": "npx",
      "args": ["-y", "@solidcommerce/mcp-server@alpha"],
      "env": { "SOLIDCOMMERCE_API_KEY": "YOUR_KEY" }
    }
  }
}

Quit and reopen Claude Desktop (MCP servers load at startup), then ask:

List 5 products from my Solid Commerce catalog.

The server targets the Solid Commerce platform API out of the box; set SOLIDCOMMERCE_API_BASE_URL in env only if you need to point elsewhere.

Claude Code

Two commands inside Claude Code — it prompts for your key on install:

/plugin marketplace add https://dev.azure.com/takeoffcommerce/SC-Base/_git/claude-code-plugin
/plugin install solidcommerce@solidcommerce

Full guide: Claude Code.

ChatGPT (OpenAI desktop & web)

ChatGPT connects to the hosted endpoint — no install, no key:

  1. Open Settings → Connectors (custom connectors require a paid ChatGPT plan; menu naming varies slightly by release — check OpenAI's current docs if it moved).
  2. Add a connector with the MCP server URL https://mcp.solidcommerce.com/mcp.
  3. Sign in when prompted — the Solid Commerce consent screen lists the requested scopes in plain English, with a company picker if you belong to more than one company.

Then ask: "How many orders came in over the weekend?" More: ChatGPT.

Gemini

Gemini CLI (works today, local): add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "solidcommerce": {
      "command": "npx",
      "args": ["-y", "@solidcommerce/mcp-server@alpha"],
      "env": { "SOLIDCOMMERCE_API_KEY": "YOUR_KEY" }
    }
  }
}

Run gemini, confirm /mcp shows solidcommerce connected, and ask the same catalog question. Full guide: Gemini CLI.

Gemini app (gemini.google.com): consumer connectors are rolled out through Google's extension program; our hosted endpoint is ready for it. Track status on Gemini — and use the CLI in the meantime.

Step 3 — What your agent can do

The server exposes 96 task-shaped tools spanning every domain of your store — catalog, orders, reports, listings, inventory, vendors, and platform administration. Real examples:

| Ask | Tool the agent uses | |---|---| | "List my products" | catalog_products_list | | "How many orders are pending shipment?" | reports_pending_shipments_list | | "What shipped this week?" | orders_shipments_list | | "Top sellers this month?" | reports_top_sellers_list | | "What's low on stock?" | reports_inventory_low_stock_list | | "Fulfill order 1234" | fulfill_order (asks you to confirm first) |

Two guarantees hold everywhere:

Step 4 — Use it from a custom agent

Any MCP client can spawn the same server. With the Anthropic Agent SDK:

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

const agent = new ClaudeAgent({
mcpServers: {
  solidcommerce: {
    command: 'npx',
    args: ['-y', '@solidcommerce/mcp-server@alpha'],
    env: { SOLIDCOMMERCE_API_KEY: process.env.SOLIDCOMMERCE_API_KEY },
  },
},
});
await agent.run('How many orders are pending shipment?');

Troubleshooting

Next steps