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

Log in to the Headless Commerce Dashboard
Go to Settings > API Keys
Click Create API Key and select type Secret (sk_ prefix)
Copy the generated key — it is only shown once

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

Configuration

Cloud (Recommended)

No installation required — just add the URL and your API key.

Claude Desktop

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

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

Claude Code

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:

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

Cursor

Add to .cursor/mcp.json:

{
  "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:

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

Authorization flow:

Register client    POST /oauth/register
Authorize user     GET  /oauth/authorize?response_type=code&code_challenge=...&scope=...
Exchange code      POST /oauth/token  (grant_type=authorization_code)
Use access token   Authorization: Bearer <access_token>
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

A :write scope automatically includes :read access for the same resource. For example, orders:write also grants orders:read.

Token lifetimes:

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

PKCE (S256) is required for all OAuth flows. Plain code_challenge_method is not supported.

Local (stdio)

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

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

Getting Started

Build with AI

API Conventions

Security

Integration Guides

Recipes

​MCP Server

​Connection Methods

​Authentication

​Getting Your API Key

​Configuration

​Cloud (Recommended)

​Claude Desktop

​Claude Code

​Cursor

​OAuth 2.0 (for third-party apps)

​Local (stdio)

​Environment Variables

​Claude Desktop

​Claude Code

​Cursor

​Local Development

​Available Tools

​Products

​Variants

​Orders

​Customers

​Inventory

​Discounts

​Fulfillments

​Categories

​Collections

​Carts & Checkout

​Payments

​Returns

​Refunds

​Regions

​Shipping Methods

​Webhooks

​Store

​Dashboard

​Resources

​Example Prompts

​Troubleshooting

​”Unauthorized” (401) when using cloud endpoint

​”Insufficient scope” when using OAuth

​”HEADLESS_COMMERCE_API_KEY environment variable is required”

​”Invalid API key” or “Secret key required for Admin API”

​Tools return empty results

​Server doesn’t appear in Claude Desktop

MCP Server

Connection Methods

Authentication

Getting Your API Key

Configuration

Cloud (Recommended)

Claude Desktop

Claude Code

Cursor

OAuth 2.0 (for third-party apps)

Local (stdio)

Environment Variables

Claude Desktop

Claude Code

Cursor

Local Development

Available Tools

Products

Variants

Orders

Customers

Inventory

Discounts

Fulfillments

Categories

Collections

Carts & Checkout

Payments

Returns

Refunds

Regions

Shipping Methods

Webhooks

Store

Dashboard

Resources

Example Prompts

Troubleshooting

”Unauthorized” (401) when using cloud endpoint

”Insufficient scope” when using OAuth

”HEADLESS_COMMERCE_API_KEY environment variable is required”

”Invalid API key” or “Secret key required for Admin API”

Tools return empty results

Server doesn’t appear in Claude Desktop