Connect your AI agent to SwatchFree (MCP)
SwatchFree runs a free Model Context Protocol (MCP) server at https://swatchfree.com/mcp. Agents such as ChatGPT, Claude, Cursor or Windsurf can search our mill fabric library by fiber, GSM and construction, read exact specs, save fabrics to your My Studio and check your orders — always on your behalf, after you approve the connection. For many buyers this is the fastest way to shortlist fabrics.
1. Connect
Server URL (all clients):
https://swatchfree.com/mcpChatGPT
Settings → Connectors (Apps) → Create / Add custom connector → paste the server URL → choose OAuth → Create.
Claude (web / desktop)
Settings → Connectors → Add custom connector → name it SwatchFree → paste the server URL → Add, then Connect.
Cursor
Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):
{
"mcpServers": {
"swatchfree": { "url": "https://swatchfree.com/mcp" }
}
}Windsurf / other MCP clients
{
"mcpServers": {
"swatchfree": { "serverUrl": "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.
Color policy: confirm with the mill color card
Mills update their colors often, so the photos show the fabric's structure and texture, not every available shade. The MCP tools therefore have no color filter. Let your agent shortlist by fiber, GSM, construction and price, then add the shortlist to a Swatch Box to receive the free mill color cards with the full, current color range.
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, pattern/texture, composition).
- Fabric specifications — full detail per SKU: composition, exact GSM value, construction, 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-onlySearch 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'. |
pattern | string | No | Pattern/texture 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",
"pattern": "solid",
"composition": "cotton",
"limit": 10
}Returns: An array of fabrics, each with id, sku, name, category, composition, gsm, pattern, construction, special_functions, certifications, sample_price_per_meter, stock_status and summary.
- All filters are optional and combined with AND.
- There is no color filter: confirm colors with the free mill color card.
get_fabric
read-onlyGet 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-onlyList 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 and sample_price_per_meter.
- Only the signed-in user's own library is returned.
save_fabric
writes dataSave 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-onlyList 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 agent workflow
Prompt you can paste into your agent:
Find 5 woven linen fabrics, 150–200 GSM, suitable for summer shirts.
Compare composition, GSM, construction and cut-sample price in a table.
Save the best 3 to my SwatchFree library.What the agent does:
search_fabricswith{ "query": "linen", "category": "woven" }, then filters by GSM.get_fabricfor each candidate to read exact specs.save_fabricfor the top 3 — they appear in My Studio → Saved Fabrics.- You open My Studio, add them to a Swatch Box and receive the free mill color cards.
More prompts:
- “Find stretch cotton knits around 220 GSM for polo shirts.”
- “What is SFXS-940620? Show composition and GSM.”
- “Where is my latest swatch order?”
FAQ
What is the SwatchFree MCP server?
It is a free Model Context Protocol endpoint at https://swatchfree.com/mcp. Any MCP-capable AI agent can search the SwatchFree mill fabric library, read exact specs per SKU, save fabrics to the buyer's My Studio and check swatch orders after the buyer signs in and approves access.
Which AI assistants can connect?
Any client that supports remote MCP servers with OAuth, including ChatGPT connectors, Claude (web and desktop), Cursor and Windsurf. Add the server URL https://swatchfree.com/mcp; OAuth settings are discovered automatically.
Can the agent search fabrics by color?
No. Mills update their colors often, so product photos show the fabric's structure and texture, not every available shade. The agent should shortlist by fiber, GSM, construction and price, then the buyer requests the free mill color card through a Swatch Box to see the full, current color range.
Does connecting an agent cost anything?
No. MCP access is free. Buyers only pay when ordering physical samples: Swatch Box $69 for up to 5 or $119 for up to 10 fabrics (color cards free, worldwide express shipping included), or cut samples of 1–10 m at $4 service fee per fabric plus shipping at cost.
Can the agent see other users' data?
No. Every call runs as the signed-in buyer via OAuth 2.1. The agent can read the public fabric catalog plus that buyer's own saved fabrics and orders only.
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_fabricneeds eitherskuorid.
Still stuck? Email coraycn@gmail.com.