Help Center

Connect your AI assistant to SwatchFree

SwatchFree supports the Model Context Protocol (MCP). External assistants such as ChatGPT, Claude or Cursor can search our fabric catalogue, read fabric specifications, save fabrics to your library and check your orders — always on your behalf, after you approve the connection.

1. Connect

Add this MCP server URL in your assistant's connector settings:

https://swatchfree.com/mcp

OAuth settings are discovered automatically from /.well-known/oauth-protected-resource — nothing to fill in manually. Clients that support dynamic registration register themselves on first connect.

2. Authorise

Start the connection in your assistant.
You are redirected to the SwatchFree sign-in page.
Review the consent screen (“Connect [assistant] to your account”) and click Approve.
The assistant can now reach the public fabric catalogue plus your own favourites and orders — never another user's data.

3. Server capabilities

Catalogue search — keyword and filter based search across the full fabric library (category, colour family, pattern, composition).
Fabric specifications — full detail per SKU: composition, weight (gsm), construction, colour, special functions, certifications, cut-sample price and stock status.
Personal fabric library — list and save favourites for the signed-in user.
Order visibility — swatch box and cut-sample orders with status and tracking, newest first.
Security — OAuth 2.1 with per-user data isolation; every call runs as the signed-in user, and no tool can read another user's library or orders.

Tool	Purpose	Mode
`search_fabrics`	Search the fabric catalogue	read-only
`get_fabric`	Full spec of one fabric by SKU or ID	read-only
`list_my_favorites`	List fabrics saved to your library	read-only
`save_fabric`	Save a fabric to your library	writes data
`list_my_orders`	List your orders with status & tracking	read-only

4. Tool reference

`search_fabrics`

read-only

Search fabrics

Search the SwatchFree fabric catalogue by keyword and optional filters.

Field	Type	Required	Description
`query`	string	No	Free-text keyword, e.g. 'cotton poplin' or 'polo pique'. Matches name, search text and SKU. Max 200 chars.
`category`	string	No	Category filter, e.g. 'knit' or 'woven'.
`color_family`	string	No	Colour family filter, e.g. 'blue'.
`pattern`	string	No	Pattern filter, e.g. 'solid' or 'stripe'.
`composition`	string	No	Composition keyword, e.g. 'cotton'.
`limit`	integer	No	1–30, default 10.

{
  "query": "cotton poplin",
  "category": "woven",
  "color_family": "blue",
  "pattern": "solid",
  "composition": "cotton",
  "limit": 10
}

Returns: An array of fabrics, each with id, sku, name, category, composition, gsm, pattern, color_name, color_family, construction, special_functions, certifications, sample_price_per_meter, stock_status and summary.

All filters are optional and combined with AND.

`get_fabric`

read-only

Get fabric details

Fetch the full detail record for one fabric by its SKU or id.

Field	Type	Required	Description
`sku`	string	No	Fabric SKU, e.g. 'SF-1024'. Max 60 chars.
`id`	uuid	No	Fabric id (UUID).

{ "sku": "SF-1024" }

Returns: The complete fabric record (all catalogue fields).

Provide either sku or id — one of the two is required.

`list_my_favorites`

read-only

List my saved fabrics

List the fabrics the signed-in user saved to their personal fabric library, newest first.

Field	Type	Required	Description
`limit`	integer	No	1–100, default 20.

{ "limit": 20 }

Returns: An array of fabrics, each with id, sku, name, category, composition, gsm, color_name and sample_price_per_meter.

Only the signed-in user's own library is returned.

`save_fabric`

writes data

Save fabric to my library

Add a fabric (by SKU or id) to the signed-in user's saved fabric library.

Field	Type	Required	Description
`sku`	string	No	Fabric SKU to save. Max 60 chars.
`id`	uuid	No	Fabric id (UUID) to save.

{ "sku": "SF-1024" }

Returns: Confirmation text and the saved fabric_id.

Provide either sku or id — one of the two is required.
Saving the same fabric twice will not create a duplicate.

`list_my_orders`

read-only

List my orders

List the signed-in user's swatch box and cut sample orders, newest first, with status and tracking.

Field	Type	Required	Description
`limit`	integer	No	1–50, default 10.

{ "limit": 10 }

Returns: An array of orders, each with order_code, order_type, status, box_tier, total_price, swatch_fabric_ids, yardage_items, tracking, created_at and updated_at.

Only the signed-in user's own orders are returned.

5. Example prompts

“Find me 100% cotton wovens suitable for shirting.”
“What is SF-1024?”
“Add SF-1024 to my fabric library.”
“Where is my latest swatch order?”

6. Troubleshooting

Not authenticated — sign in and approve the connection again.
Fabric not found — the SKU or ID does not exist; search again with search_fabrics.
Missing parameter — e.g. get_fabric needs either sku or id.

Still stuck? Email hello@swatchfree.com.