Faire MCP tools

MCP tool faire_list_orders

Lists your wholesale orders, newest first. Filter by status or by the date an order was placed to see what is new since your last check. Totals are wholesale prices. Pages hold up to 100 orders; pass next_cursor back as cursor for the next page.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_list_orders",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "orders": [
      {
        "order_id": "bo_8x2k4m9q",
        "retailer": "Example Gift Shop",
        "retailer_id": "r_61d0c3",
        "status": "New",
        "total": 408,
        "currency": "USD",
        "placed_at": "2026-10-08T15:12:00Z",
        "ship_by": "2026-10-16"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

MCP tool faire_get_order

Returns one order in full: each item with SKU, quantity and wholesale price, the ship-to address and any shipments already added. The order total is the sum of the item lines.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_order",
    "arguments": {
      "order_id": "order_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "bo_8x2k4m9q",
    "status": "New",
    "retailer": "Example Gift Shop",
    "items": [
      {
        "sku": "CNDL-AMB-01",
        "name": "Amber candle",
        "quantity": 12,
        "unit_price": 14,
        "line_total": 168
      },
      {
        "sku": "CNDL-CDR-02",
        "name": "Cedar candle",
        "quantity": 12,
        "unit_price": 14,
        "line_total": 168
      },
      {
        "sku": "MTCH-BOX-01",
        "name": "Match box",
        "quantity": 12,
        "unit_price": 6,
        "line_total": 72
      }
    ],
    "total": 408,
    "currency": "USD",
    "ship_to": {
      "city": "Portland",
      "region": "OR",
      "country": "US"
    },
    "shipments": []
  },
  "isError": false
}

MCP tool faire_get_inventory

Returns the on-hand quantity Faire shows for each variant, keyed by SKU. Pass skus to check only some variants.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_inventory",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "items": [
      {
        "sku": "CNDL-AMB-01",
        "quantity": 84
      },
      {
        "sku": "CNDL-CDR-02",
        "quantity": 0
      }
    ]
  },
  "isError": false
}

MCP tool faire_list_customers

Lists retailers on your customer list, with how many orders each placed and the date of the last one. Use last_order_before to find retailers who stopped ordering. Pass retailer_id values to send_campaign.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_list_customers",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "customers": [
      {
        "retailer_id": "r_61d0c3",
        "name": "Example Gift Shop",
        "orders": 3,
        "last_order_at": "2026-04-12"
      },
      {
        "retailer_id": "r_9a3e77",
        "name": "Harbor Home Store",
        "orders": 1,
        "last_order_at": "2026-03-02"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

MCP tool faire_list_conversations

Lists your conversations with retailers, most recent first. Set needs_reply to see only the threads waiting for you, the ones the portal groups under Needs Reply.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_list_conversations",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversations": [
      {
        "conversation_id": "cv_4f7a21",
        "retailer": "Example Gift Shop",
        "last_message": "When will the candles ship?",
        "needs_reply": true,
        "updated_at": "2026-10-09T10:41:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

MCP tool faire_get_conversation

Returns the messages of one conversation, oldest first, so your agent reads the thread in order before answering. Attachments are listed by file name only.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_conversation",
    "arguments": {
      "conversation_id": "conversation_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversation_id": "cv_4f7a21",
    "retailer": "Example Gift Shop",
    "messages": [
      {
        "from": "retailer",
        "body": "Hi! When will the candles ship?",
        "sent_at": "2026-10-09T10:41:00Z"
      }
    ]
  },
  "isError": false
}

MCP tool faire_get_faire_direct_link

Returns the Faire Direct link from your brand portal. A retailer who signs up for Faire through this link can qualify for 0% commission on orders with you. Use it in campaigns and messages.

Parameters

No parameters.

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_get_faire_direct_link",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "url": "https://www.faire.com/direct/example-candle-co"
  },
  "isError": false
}

MCP tool faire_accept_order

Accepts one new order with a scheduled ship date. Faire emails the retailer that the order is processing. Replacement orders are not covered by Faire's auto-accept, so use this tool for them. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_accept_order",
    "arguments": {
      "order_id": "order_8c41d2",
      "ship_by": "2026-10-01"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "bo_8x2k4m9q",
    "status": "Processing",
    "ship_by": "2026-10-16"
  },
  "isError": false
}

MCP tool faire_add_shipment

Adds a shipment to an order, the same as Ship on your own in the portal: carrier, tracking number and package cost. Faire emails the retailer a tracking link when the order ships. If Faire does not support the carrier, it marks the order shipped on its own 72 hours after the date you added the tracking. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_add_shipment",
    "arguments": {
      "order_id": "bo_8x2k4m9q",
      "carrier": "UPS",
      "tracking_code": "1Z999AA10123456784",
      "package_cost": 12.4
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "bo_8x2k4m9q",
    "status": "Shipped",
    "shipment": {
      "carrier": "UPS",
      "tracking_code": "1Z999AA10123456784",
      "package_cost": 12.4
    }
  },
  "isError": false
}

MCP tool faire_update_inventory

Sets the available quantity for one or more variants by SKU, so Faire matches your warehouse. It reaches no one directly and one more call restores the old numbers, so update_inventory runs without asking first.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_update_inventory",
    "arguments": {
      "items": [
        "items"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "updated": [
      {
        "sku": "CNDL-AMB-01",
        "quantity": 120
      },
      {
        "sku": "CNDL-CDR-02",
        "quantity": 48
      }
    ]
  },
  "isError": false
}

MCP tool faire_reply_to_message

Sends a text message in an existing conversation, under your brand name. It cannot start a conversation and cannot attach files; use the portal on desktop for attachments. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_reply_to_message",
    "arguments": {
      "conversation_id": "cv_4f7a21",
      "body": "Thanks for asking! Your candles ship on Friday 16 Oct and the tracking link follows by email."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "conversation_id": "cv_4f7a21",
    "message_id": "msg_9d20",
    "status": "sent"
  },
  "isError": false
}

MCP tool faire_send_campaign

Sends an email through Faire's Campaigns tool to the retailers you choose. Sending is free, but Faire limits it: 1 email a week to retailers who have not ordered from you, 2 a week to existing customers, and 1 campaign per retailer per day. Keep the bounce rate under 10% and the spam rate under 0.1% per campaign. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "faire_send_campaign",
    "arguments": {
      "subject": "Your fall candle restock",
      "body_markdown": "Hi! Our fall candles are in stock, including Amber. Your last order was in July, so here is what is new before the holidays.",
      "retailer_ids": [
        "r_9a3e77",
        "r_61d0c3"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "campaign_id": "cp_30b9",
    "status": "sent",
    "recipients": 3,
    "subject": "Your fall restock is ready"
  },
  "isError": false
}