> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI agents to your Headless Commerce store

# MCP Server

The MCP (Model Context Protocol) server lets AI agents like Claude, ChatGPT, and Cursor manage your store through natural language.

```
                    ┌── Cloud (HTTP) ──► https://mcp.headlesscommerce.io/mcp
AI Agent ───────────┤                                │
(Claude, Cursor,    └── Local (stdio) ─► npx @headless-commerce/mcp-server
 ChatGPT)                                            │
                                               SDK ──► Headless Commerce API
```

The MCP server is **stateless** — it holds no data and acts purely as a bridge between AI agents and the Headless Commerce API.

## Connection Methods

|               | Cloud (Recommended)    | Local (stdio)           |
| ------------- | ---------------------- | ----------------------- |
| **Setup**     | URL + API key or OAuth | Requires Node.js        |
| **Transport** | Streamable HTTP        | stdio (JSON-RPC)        |
| **Auth**      | API key or OAuth 2.0   | API key only            |
| **Updates**   | Always latest          | Manual `npm update`     |
| **Offline**   | No                     | Yes                     |
| **Best for**  | Production, most users | Air-gapped, self-hosted |

## Authentication

The Cloud MCP server supports two authentication methods:

| Method              | Best for                               | Scopes                    |
| ------------------- | -------------------------------------- | ------------------------- |
| **API Key** (`sk_`) | Quick setup, full admin access         | `admin` (all permissions) |
| **OAuth 2.0**       | Third-party apps, granular permissions | Configurable per-resource |

### Getting Your API Key

1. Log in to the [Headless Commerce Dashboard](https://app.headlesscommerce.io)
2. Go to **Settings > API Keys**
3. Click **Create API Key** and select type **Secret** (`sk_` prefix)
4. Copy the generated key — it is only shown once

<Warning>
  MCP server requires a **Secret Key** (`sk_`). Publishable keys (`pk_`) are for storefront use only and will be rejected by admin endpoints.
</Warning>

## Configuration

***

### Cloud (Recommended)

<Info>No installation required — just add the URL and your API key.</Info>

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "url": "https://mcp.headlesscommerce.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}
```

#### Claude Code

```bash theme={null}
claude mcp add headless-commerce \
  --transport http \
  --url https://mcp.headlesscommerce.io/mcp \
  --header "Authorization: Bearer sk_live_your_api_key"
```

Or add to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "url": "https://mcp.headlesscommerce.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "url": "https://mcp.headlesscommerce.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}
```

#### OAuth 2.0 (for third-party apps)

For apps that need granular, scoped access instead of full admin, the Cloud MCP server supports **OAuth 2.0 with PKCE**.

MCP clients that support OAuth can automatically discover the auth configuration:

1. Fetch `https://mcp.headlesscommerce.io/.well-known/mcp.json` — returns the OAuth metadata URLs
2. Fetch `https://mcp.headlesscommerce.io/.well-known/oauth-protected-resource` — returns supported scopes and authorization server
3. Fetch `https://api.headlesscommerce.io/.well-known/oauth-authorization-server` — returns authorization and token endpoints

**Authorization flow:**

```
1. Register client    POST /oauth/register
2. Authorize user     GET  /oauth/authorize?response_type=code&code_challenge=...&scope=...
3. Exchange code      POST /oauth/token  (grant_type=authorization_code)
4. Use access token   Authorization: Bearer <access_token>
5. Refresh token      POST /oauth/token  (grant_type=refresh_token)
```

**Available scopes:**

| Scope             | Description                            |
| ----------------- | -------------------------------------- |
| `admin`           | Full access to all resources           |
| `products:read`   | View products, categories, collections |
| `products:write`  | Create and update products             |
| `orders:read`     | View orders                            |
| `orders:write`    | Manage orders (confirm, cancel)        |
| `customers:read`  | View customers                         |
| `customers:write` | Manage customers                       |
| `inventory:read`  | View inventory levels                  |
| `inventory:write` | Adjust inventory                       |
| `discounts:read`  | View discounts                         |
| `discounts:write` | Create and manage discounts            |
| `store:read`      | View store settings                    |
| `store:write`     | Update store settings                  |
| `dashboard:read`  | View dashboard analytics               |

<Info>
  A `:write` scope automatically includes `:read` access for the same resource. For example, `orders:write` also grants `orders:read`.
</Info>

**Token lifetimes:**

| Token              | Lifetime                 |
| ------------------ | ------------------------ |
| Authorization code | 10 minutes (single-use)  |
| Access token       | 1 hour                   |
| Refresh token      | 30 days (rotated on use) |

<Note>
  PKCE (`S256`) is **required** for all OAuth flows. Plain `code_challenge_method` is not supported.
</Note>

***

### Local (stdio)

If you prefer running the MCP server locally, install via npm:

```bash theme={null}
npm install -g @headless-commerce/mcp-server
# or run directly
npx @headless-commerce/mcp-server
```

#### Environment Variables

| Variable                    | Required | Default                              | Description                           |
| --------------------------- | -------- | ------------------------------------ | ------------------------------------- |
| `HEADLESS_COMMERCE_API_KEY` | Yes      | —                                    | Admin API key (`sk_` prefix)          |
| `HEADLESS_COMMERCE_API_URL` | No       | `https://api.headlesscommerce.io/v1` | API base URL (override for local dev) |

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "command": "npx",
      "args": ["-y", "@headless-commerce/mcp-server"],
      "env": {
        "HEADLESS_COMMERCE_API_KEY": "sk_live_your_api_key"
      }
    }
  }
}
```

#### Claude Code

Add to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "command": "npx",
      "args": ["-y", "@headless-commerce/mcp-server"],
      "env": {
        "HEADLESS_COMMERCE_API_KEY": "sk_live_your_api_key"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "command": "npx",
      "args": ["-y", "@headless-commerce/mcp-server"],
      "env": {
        "HEADLESS_COMMERCE_API_KEY": "sk_live_your_api_key"
      }
    }
  }
}
```

#### Local Development

For local development, override the API URL:

```json theme={null}
{
  "env": {
    "HEADLESS_COMMERCE_API_KEY": "sk_test_your_api_key",
    "HEADLESS_COMMERCE_API_URL": "http://localhost:3010/v1"
  }
}
```

## Available Tools

### Products

| Tool             | Description                                            |
| ---------------- | ------------------------------------------------------ |
| `list_products`  | List products with search, filtering, and pagination   |
| `get_product`    | Get a product by ID with variants, images, and options |
| `create_product` | Create a new product                                   |
| `update_product` | Update product name, description, status, tags         |

### Variants

| Tool             | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `create_variant` | Create a variant with price (in smallest currency unit) |

### Orders

| Tool            | Description                                          |
| --------------- | ---------------------------------------------------- |
| `list_orders`   | List orders with status/payment/fulfillment filters  |
| `get_order`     | Get order details with lines, payments, fulfillments |
| `confirm_order` | Confirm a pending order                              |
| `cancel_order`  | Cancel an order with optional reason                 |

### Customers

| Tool             | Description                                 |
| ---------------- | ------------------------------------------- |
| `list_customers` | List customers with search by name or email |
| `get_customer`   | Get a customer by ID                        |

### Inventory

| Tool               | Description                             |
| ------------------ | --------------------------------------- |
| `list_inventory`   | List inventory levels for all variants  |
| `adjust_inventory` | Adjust stock quantity (+/-) with reason |

### Discounts

| Tool              | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `list_discounts`  | List all discount codes/promotions                      |
| `create_discount` | Create a discount (fixed, percentage, or free shipping) |

### Fulfillments

| Tool                  | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `create_fulfillment`  | Create a fulfillment for an order with tracking info |
| `update_fulfillment`  | Update tracking information                          |
| `ship_fulfillment`    | Mark a fulfillment as shipped                        |
| `deliver_fulfillment` | Mark a fulfillment as delivered                      |

### Categories

| Tool              | Description           |
| ----------------- | --------------------- |
| `list_categories` | List all categories   |
| `create_category` | Create a new category |
| `update_category` | Update a category     |
| `delete_category` | Delete a category     |

### Collections

| Tool                | Description                          |
| ------------------- | ------------------------------------ |
| `list_collections`  | List all collections                 |
| `create_collection` | Create a collection (manual or auto) |
| `update_collection` | Update a collection                  |
| `delete_collection` | Delete a collection                  |

### Carts & Checkout

| Tool                  | Description                        |
| --------------------- | ---------------------------------- |
| `create_cart`         | Create a new shopping cart         |
| `get_cart`            | Get a cart with items and totals   |
| `add_cart_item`       | Add a product variant to a cart    |
| `update_cart_item`    | Update cart item quantity          |
| `remove_cart_item`    | Remove an item from a cart         |
| `apply_cart_discount` | Apply a discount code to a cart    |
| `checkout_cart`       | Checkout a cart to create an order |

### Payments

| Tool               | Description                          |
| ------------------ | ------------------------------------ |
| `create_payment`   | Record a manual payment for an order |
| `complete_payment` | Mark a payment as completed          |

### Returns

| Tool              | Description                          |
| ----------------- | ------------------------------------ |
| `list_returns`    | List all returns                     |
| `get_return`      | Get return details                   |
| `create_return`   | Create a return request for an order |
| `approve_return`  | Approve a return                     |
| `reject_return`   | Reject a return                      |
| `receive_return`  | Mark returned items as received      |
| `complete_return` | Complete a return                    |

### Refunds

| Tool            | Description                  |
| --------------- | ---------------------------- |
| `create_refund` | Create a refund for an order |

### Regions

| Tool                  | Description                               |
| --------------------- | ----------------------------------------- |
| `list_regions`        | List all regions                          |
| `create_region`       | Create a region with currency and tax     |
| `update_region`       | Update a region                           |
| `delete_region`       | Delete a region                           |
| `upsert_region_price` | Set region-specific pricing for a variant |

### Shipping Methods

| Tool                     | Description               |
| ------------------------ | ------------------------- |
| `list_shipping_methods`  | List all shipping methods |
| `create_shipping_method` | Create a shipping method  |
| `update_shipping_method` | Update a shipping method  |

### Webhooks

| Tool             | Description                    |
| ---------------- | ------------------------------ |
| `list_webhooks`  | List webhook subscriptions     |
| `create_webhook` | Create a webhook subscription  |
| `test_webhook`   | Send a test event to a webhook |

### Store

| Tool           | Description                           |
| -------------- | ------------------------------------- |
| `get_store`    | Get store settings and configuration  |
| `update_store` | Update store name, currency, metadata |

### Dashboard

| Tool                  | Description                                         |
| --------------------- | --------------------------------------------------- |
| `get_dashboard_stats` | Get revenue, orders, customers, and recent activity |

## Resources

| Resource      | URI              | Description                                                                          |
| ------------- | ---------------- | ------------------------------------------------------------------------------------ |
| API Reference | `openapi://spec` | Embedded OpenAPI spec — AI agents read this automatically to understand the full API |

## Example Prompts

Once configured, try asking your AI agent:

* "Show me all orders from today"
* "Create a new product called 'Wireless Headphones' at \$49.99"
* "What's the current inventory for our best-selling items?"
* "Cancel order ord\_abc123 — customer requested refund"
* "Give me a dashboard summary of the last 30 days"
* "List all active discount codes"

## Troubleshooting

### "Unauthorized" (401) when using cloud endpoint

* Ensure the header is `Authorization: Bearer <token>` (include the `Bearer` prefix)
* For API keys: verify the key starts with `sk_` (not `pk_`) and is active in Dashboard > Settings > API Keys
* For OAuth tokens: verify the access token has not expired (1-hour lifetime) — refresh it using the refresh token

### "Insufficient scope" when using OAuth

* The OAuth token does not have the required scope for the requested tool
* Check which scopes were granted during authorization
* Request additional scopes by re-authorizing with a broader `scope` parameter

### "HEADLESS\_COMMERCE\_API\_KEY environment variable is required"

This applies to the local (stdio) server. It exits immediately if no API key is provided. Ensure the `env` block in your MCP config has the key set.

### "Invalid API key" or "Secret key required for Admin API"

* Verify the key starts with `sk_` (not `pk_`)
* Check that the key is still active in Dashboard > Settings > API Keys

### Tools return empty results

* Confirm the API server is running and accessible at the configured URL
* For local dev, make sure `HEADLESS_COMMERCE_API_URL` is set to `http://localhost:3010/v1`
* Check that your store has data (products, orders, etc.)

### Server doesn't appear in Claude Desktop

* Restart Claude Desktop after editing the config file
* Verify the JSON is valid (no trailing commas, correct nesting)
* Check `~/Library/Logs/Claude/mcp*.log` for error messages