MCP Server (AI Agents)

The @swft-checkout/mcp package exposes a Model Context Protocol server that lets AI agents — Claude, GPT-4o, Gemini, or any MCP-compatible runtime — interact with Swft directly. Agents can browse products, inspect analytics, check cart recovery stats, and place orders on behalf of customers.

Installation

npm install -g @swft-checkout/mcp

Or run without installing:

npx @swft-checkout/mcp

Configuration

The MCP server reads your API key from the environment:

export SWFT_API_KEY=sk_swft_live_xxxxxxxxxxxxxxxx

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "swft": {
      "command": "npx",
      "args":    ["-y", "@swft-checkout/mcp"],
      "env": {
        "SWFT_API_KEY": "sk_swft_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see “swft” listed in the MCP tools panel.

Available tools

`swft_analytics`

Returns checkout funnel metrics for the merchant over a given period.

Parameters:

Name	Type	Description
`period`	`string`	`7d`, `30d`, `90d`, or ISO date range (`2026-01-01/2026-03-31`)
`breakdown`	`string`	Optional. `template`, `device`, `country`, `source`

Example output:

{
  "sessions": 4821,
  "completions": 2341,
  "conversionRate": 0.486,
  "revenue": 142850.00,
  "avgOrderValue": 61.02,
  "topDropOffStep": "payment"
}

`swft_sessions`

Lists recent checkout sessions with status, cart value, and completion state. Useful for diagnosing drop-off.

Parameters:

Name	Type	Description
`status`	`string`	`all`, `completed`, `abandoned`, `recovering`
`limit`	`number`	Max results (default 20, max 100)
`cursor`	`string`	Pagination cursor from previous response

`swft_merchant_info`

Returns the full merchant config: enabled modules, active template, connected Stripe account, and plan details.

Parameters: none.

`swft_recovery_stats`

Returns cart recovery email performance: send rate, open rate, click rate, and recovered revenue.

Parameters:

Name	Type	Description
`period`	`string`	`7d`, `30d`, `90d`

`swft_get_products`

Searches the merchant’s WooCommerce product catalogue. Returns product name, SKU, price, stock status, and image URL.

Parameters:

Name	Type	Description
`query`	`string`	Search term
`limit`	`number`	Max results (default 10)
`inStock`	`boolean`	Filter to in-stock only
`category`	`string`	WooCommerce category slug

`swft_create_checkout`

Creates a Swft checkout session and returns a URL the customer can be directed to. This is the tool an AI agent uses to place an order on behalf of a customer.

Parameters:

Name	Type	Description
`lineItems`	`array`	Product ID / variation ID + quantity pairs
`customer`	`object`	Pre-fill: email, name, billing address
`coupon`	`string`	Optional coupon code to apply
`b2b`	`boolean`	Enable B2B mode for this session
`note`	`string`	Order note added by the agent

Example:

{
  "lineItems": [
    { "productId": 1842, "quantity": 1 }
  ],
  "customer": {
    "email":     "[email protected]",
    "firstName": "Jane",
    "lastName":  "Smith"
  },
  "note": "Placed via AI agent on behalf of customer"
}

Returns:

{
  "sessionId":   "sess_xxxxxxxx",
  "checkoutUrl": "https://checkout.swft.co.uk/s/sess_xxxxxxxx",
  "expiresAt":   "2026-04-26T14:30:00Z"
}

Example: agent placing an order

Here is an example conversation where an AI agent uses the MCP tools to complete a purchase:

User: Can you order me two tins of the Columbian Dark Roast and apply the WELCOME10 discount?

Agent (internal): Calls swft_get_products with query: "Columbian Dark Roast" → gets product ID 2091, price £8.50, in stock.

Calls swft_create_checkout with lineItems: [{productId: 2091, quantity: 2}], coupon: "WELCOME10", customer: {email: "[email protected]"}.

Returns checkout URL.

Agent: I’ve set up your order for 2 × Columbian Dark Roast (£15.30 after 10% discount). Complete payment here: [checkout link]. The link expires in 60 minutes.