Help Center

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/mcp

ChatGPT

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

  1. Start the connection in your assistant.
  2. You are redirected to the SwatchFree sign-in page.
  3. Review the consent screen (“Connect [assistant] to your account”) and click Approve.
  4. 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.
ToolPurposeMode
search_fabricsSearch the fabric catalogueread-only
get_fabricFull spec of one fabric by SKU or IDread-only
list_my_favoritesList fabrics saved to your libraryread-only
save_fabricSave a fabric to your librarywrites data
list_my_ordersList your orders with status & trackingread-only

4. Tool reference

search_fabrics

read-only

Search fabrics

Search the SwatchFree fabric catalogue by keyword and optional filters.

FieldTypeRequiredDescription
querystringNoFree-text keyword, e.g. 'cotton poplin' or 'polo pique'. Matches name, search text and SKU. Max 200 chars.
categorystringNoCategory filter, e.g. 'knit' or 'woven'.
patternstringNoPattern/texture filter, e.g. 'solid' or 'stripe'.
compositionstringNoComposition keyword, e.g. 'cotton'.
limitintegerNo1–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-only

Get fabric details

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

FieldTypeRequiredDescription
skustringNoFabric SKU, e.g. 'SF-1024'. Max 60 chars.
iduuidNoFabric 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.

FieldTypeRequiredDescription
limitintegerNo1–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 data

Save fabric to my library

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

FieldTypeRequiredDescription
skustringNoFabric SKU to save. Max 60 chars.
iduuidNoFabric 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.

FieldTypeRequiredDescription
limitintegerNo1–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:

  1. search_fabrics with { "query": "linen", "category": "woven" }, then filters by GSM.
  2. get_fabric for each candidate to read exact specs.
  3. save_fabric for the top 3 — they appear in My Studio → Saved Fabrics.
  4. 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_fabric needs either sku or id.

Still stuck? Email coraycn@gmail.com.