> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fourthwall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect AI assistants to manage your Fourthwall shop with the Model Context Protocol
The Fourthwall MCP server gives AI assistants direct access to your shop — products, orders, promotions, collections, analytics, and more. Assistants can both **read** your shop data and **make changes** on your behalf.
## What You Can Do
Once connected, you can ask your AI assistant things like:
**Read & analyze**
* *"Show me my top-selling products this month"*
* *"List all unfulfilled orders from the past week"*
* *"What's my conversion rate compared to last month?"*
* *"Find all orders from [customer@example.com](mailto:customer@example.com)"*
* *"What are my sales by country this quarter?"*
* *"How many active members do I have?"*
* *"Search help docs for how to set up shipping profiles"*
**Manage & update**
* *"Create a 20% off promotion for this weekend"*
* *"Bump the price on all my t-shirt variants by \$2"*
* *"Unpublish the sold-out hoodie"*
* *"Refund order D3XZFWPP"*
* *"Create a new collection and add my summer products to it"*
* *"Issue 10 gift cards worth \$25 each"*
## Connect to the MCP Server
**Server URL:** `https://mcp.fourthwall.com` (Streamable HTTP)
1. Open Claude settings and navigate to **Connectors**
2. Select **Add custom connector**
3. Enter name: `Fourthwall`
4. Enter URL: `https://mcp.fourthwall.com`
5. Select **Add**
6. You'll be prompted to log in with your Fourthwall account
Run in your terminal:
```bash theme={null}
claude mcp add --transport http fourthwall https://mcp.fourthwall.com
```
On first use, you'll be redirected to log in with your Fourthwall account.
Run in your terminal:
```bash theme={null}
codex mcp add fourthwall --url https://mcp.fourthwall.com
```
Then start the OAuth flow to log in with your Fourthwall account:
```bash theme={null}
codex mcp login fourthwall
```
Or add the server to `~/.codex/config.toml` by hand and run `codex mcp login fourthwall`:
```toml theme={null}
[mcp_servers.fourthwall]
url = "https://mcp.fourthwall.com"
```
1. Open command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Search for **Open MCP settings**
3. Add to your `mcp.json`:
```json theme={null}
{
"mcpServers": {
"fourthwall": {
"url": "https://mcp.fourthwall.com"
}
}
}
```
1. Open command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Search for **MCP: Add Server**
3. Select **HTTP**
4. Enter URL: `https://mcp.fourthwall.com`
5. Enter name: `fourthwall`
Add to your `~/.gemini/settings.json`:
```json theme={null}
{
"mcpServers": {
"fourthwall": {
"httpUrl": "https://mcp.fourthwall.com"
}
}
}
```
Any MCP-compatible client can connect using the Streamable HTTP transport:
* **URL:** `https://mcp.fourthwall.com`
* **Transport:** Streamable HTTP
* **Authentication:** OAuth 2.0 (initiated automatically on first connection)
## Authentication
The MCP server uses **OAuth 2.0** to authenticate with your Fourthwall account. When you connect for the first time:
1. Your AI client opens a browser window to Fourthwall's login page
2. You log in with your existing Fourthwall credentials
3. You select which shop to connect (if you manage multiple shops)
4. The session is established — you're ready to go
## Available Tools
The MCP server exposes tools across the following categories. Most are **read** tools that retrieve data; the [Write & Management Tools](#write-management-tools) section below covers tools that change your shop.
### Search & Knowledge
| Tool | Description |
| ---------------- | --------------------------------------------------------------------------------- |
| `omni_search` | Search across orders, products, promotions, and collections by name, email, or ID |
| `omni_knowledge` | Search Fourthwall's help docs and knowledge base |
| `omni_escalate` | Hand the conversation off to Fourthwall's human support team |
### Products & Catalog
| Tool | Description |
| ----------------------------------------- | ---------------------------------------------- |
| `ecommerce_get-offers` | List all products in your shop |
| `ecommerce_get-offers-by-ids` | Get specific products by ID |
| `ecommerce_get-catalog-products` | Browse the Fourthwall product catalog |
| `ecommerce_get-catalog-products-by-slugs` | Get catalog products by URL slugs |
| `ecommerce_get-catalog-product-details` | Get details for a catalog product |
| `ecommerce_validate-combined-listing` | Validate a combined listing before creating it |
### Orders & Fulfillment
| Tool | Description |
| ----------------------------------------- | ---------------------------------------------- |
| `ecommerce_get-orders` | List orders with filters |
| `ecommerce_get-orders-statistics` | Get order statistics and summaries |
| `ecommerce_get-order-details-by-ids` | Get full details for specific orders |
| `ecommerce_get-unfulfilled-orders` | List orders awaiting fulfillment |
| `ecommerce_get-order-cancellation-by-ids` | Check cancellation status |
| `ecommerce_get-fulfillment-details` | Get fulfillment tracking information |
| `ecommerce_preview-cancel-cost` | Preview the cost impact of cancelling an order |
| `ecommerce_preview-refund-cost` | Preview the cost impact of refunding an order |
### Collections
| Tool | Description |
| ---------------------------------- | ------------------------ |
| `ecommerce_get-collections` | List all collections |
| `ecommerce_get-collections-by-ids` | Get specific collections |
### Promotions
| Tool | Description |
| --------------------------------- | ----------------------- |
| `ecommerce_get-promotions` | List all promotions |
| `ecommerce_get-promotions-by-ids` | Get specific promotions |
### Gift Cards & Giveaways
| Tool | Description |
| ------------------------------ | ---------------------- |
| `ecommerce_get-gift-card` | Get a single gift card |
| `ecommerce_get-gift-cards` | List gift cards |
| `ecommerce_get-giveaway-links` | List giveaway links |
### Analytics & Reports
| Tool | Description |
| ------------------------------------------------- | ---------------------------- |
| `ecommerce_get-sales-over-time-report` | Revenue over a date range |
| `ecommerce_get-top-products-by-units-sold-report` | Best-selling products |
| `ecommerce_get-average-order-value-report` | Average order value trends |
| `ecommerce_get-conversion-rates-report` | Storefront conversion rates |
| `ecommerce_get-visitors-report` | Visitor traffic data |
| `ecommerce_get-sales-by-country-report` | Revenue breakdown by country |
| `ecommerce_get-sales-by-source-report` | Revenue by traffic source |
| `ecommerce_get-sales-by-utm-report` | Revenue by UTM campaign |
| `ecommerce_get-sessions-by-source-report` | Sessions by traffic source |
| `ecommerce_get-customers-over-time-report` | Customer growth over time |
| `ecommerce_get-total-profit-report` | Total profit overview |
| `ecommerce_get-contributions-per-type-report` | Revenue by product type |
| `ecommerce_get-payment-method-used-report` | Payment method breakdown |
| `ecommerce_get-affiliate-earnings-report` | Affiliate earnings summary |
### Memberships
| Tool | Description |
| ---------------------------------------------------------- | ------------------------------------- |
| `ecommerce_get-membership-active-members-report` | Active members overview |
| `ecommerce_get-membership-new-members-report` | New member signups |
| `ecommerce_get-membership-cancelled-members-report` | Cancellation data |
| `ecommerce_get-membership-free-trials-report` | Free trial activity |
| `ecommerce_get-membership-free-accounts-report` | Free account data |
| `ecommerce_get-membership-tier-activity-report` | Activity by tier |
| `ecommerce_get-membership-top-tiers-by-new-members-report` | Top-performing tiers |
| `ecommerce_get-membership-post-statistics-report` | Engagement stats for membership posts |
| `ecommerce_get-membership-mux-number-of-plays-report` | Video play counts |
| `ecommerce_get-membership-mux-total-play-time-report` | Total video watch time |
| `ecommerce_get-membership-mux-most-played-content-report` | Most-played membership videos |
### Integrations & Shipping
| Tool | Description |
| ------------------------------------ | ------------------------------ |
| `ecommerce_get-all-integrations` | List connected integrations |
| `ecommerce_get-tiktok-configuration` | TikTok integration settings |
| `ecommerce_get-tiktok-products` | TikTok product sync status |
| `ecommerce_get-youtube-integrations` | YouTube integration settings |
| `ecommerce_get-youtube-products` | YouTube product sync status |
| `ecommerce_get-shipping-profiles` | Shipping profile configuration |
| `ecommerce_get-shipping-flat-rates` | Flat rate shipping settings |
| `ecommerce_get-dns-entries` | Custom domain DNS records |
| `ecommerce_validate-dns-entries` | Validate DNS configuration |
### Shop & Account
| Tool | Description |
| -------------------------------------------- | ------------------------------------ |
| `ecommerce_get-current-shop` | Your shop details |
| `ecommerce_get-current-subscription` | Your current Fourthwall plan |
| `ecommerce_get-available-plans` | Available plan options |
| `ecommerce_get-subscription-limits` | Plan limits and usage |
| `ecommerce_get-shop-permissions` | Your account permissions |
| `ecommerce_get-user-connections` | Shops connected to your account |
| `ecommerce_get-payout-info` | Payout configuration |
| `ecommerce_get-payout-transactions` | Payout transaction history |
| `ecommerce_get-sample-credit-balance` | Sample credit balance |
| `ecommerce_get-personalized-recommendations` | Personalized product recommendations |
## Write & Management Tools
Beyond reading data, the MCP server can make changes to your shop. Write operations modify live data, so your assistant will typically confirm the details before acting, and your account permissions still apply — some actions require **Manager** or **Super Admin** access.
### Products
| Tool | Description |
| -------------------------------------------- | ---------------------------------- |
| `ecommerce_create-digital-offer` | Create a new digital product |
| `ecommerce_duplicate-offer` | Duplicate an existing product |
| `ecommerce_update-offer` | Update a product's details |
| `ecommerce_update-offer-slug` | Change a product's URL slug |
| `ecommerce_update-offer-status` | Publish or unpublish a product |
| `ecommerce_update-offer-variant` | Update a product variant |
| `ecommerce_bulk-update-offer-variant-prices` | Bulk-update prices across variants |
| `ecommerce_create-bundle` | Create a product bundle |
| `ecommerce_update-bundle` | Update a product bundle |
| `ecommerce_create-combined-listing` | Create a combined listing |
| `ecommerce_update-combined-listing` | Update a combined listing |
### Collections
| Tool | Description |
| ---------------------------------------------- | ---------------------------------------------- |
| `ecommerce_create-collection` | Create a new collection |
| `ecommerce_update-collection-details` | Update a collection's name and description |
| `ecommerce_update-collection-slug` | Change a collection's URL slug |
| `ecommerce_update-collection-state` | Publish or unpublish a collection |
| `ecommerce_update-collection-availability` | Set a collection's availability |
| `ecommerce_update-collection-sorting-strategy` | Change how products are sorted in a collection |
### Promotions
| Tool | Description |
| --------------------------------------- | ---------------------------------------- |
| `ecommerce_create-shop-promotion` | Create a shop-wide promotion or discount |
| `ecommerce_create-membership-promotion` | Create a membership promotion |
| `ecommerce_update-promotion` | Update an existing promotion |
| `ecommerce_activate-promotion` | Activate a promotion |
| `ecommerce_deactivate-promotion` | Deactivate a promotion |
### Orders & Fulfillment
| Tool | Description |
| ----------------------------------------- | ----------------------------------------------- |
| `ecommerce_cancel-order` | Cancel an order |
| `ecommerce_refund-order` | Refund an order |
| `ecommerce_change-order-shipping-address` | Update an order's shipping address |
| `ecommerce_edit-self-fulfilled-tracking` | Edit tracking details for self-fulfilled orders |
### Gift Cards & Giveaways
| Tool | Description |
| --------------------------------- | ---------------------------- |
| `ecommerce_create-gift-cards` | Issue one or more gift cards |
| `ecommerce_create-giveaway-links` | Create giveaway links |
| `ecommerce_cancel-giveaway-links` | Cancel giveaway links |
### Samples & Shop
| Tool | Description |
| --------------------------------------- | ------------------------------------------ |
| `ecommerce_create-sample-checkout` | Create a checkout to order product samples |
| `ecommerce_update-shop-site-status` | Bring your shop's site online or offline |
| `ecommerce_update-shop-post-onboarding` | Update your shop's post-onboarding state |
### Product Design
Create product designs from artwork and turn them into live products. These tools power the AI-assisted product creation flow.
| Tool | Description |
| -------------------------------------------- | --------------------------------------------- |
| `ecommerce_generate-product-design-previews` | Generate design previews on a catalog product |
| `ecommerce_rerender-design-previews` | Re-render design previews |
| `ecommerce_create-offers-from-designs` | Create products from finished designs |
| `ecommerce_create-offers-from-products` | Create products from catalog products |
| `ecommerce_inspect-design` | Inspect a product design |
| `ecommerce_edit-design` | Edit a product design |
| `ecommerce_add-design-region` | Add a print region to a design |
| `ecommerce_remove-design-region` | Remove a print region from a design |
| `ecommerce_get-design-pipeline-status` | Check the status of a design generation job |
| `ecommerce_get-draft-attributes` | Get a product draft's color and size options |
| `ecommerce_add-draft-colors` | Add colors to a product draft |
| `ecommerce_remove-draft-colors` | Remove colors from a product draft |
| `ecommerce_add-draft-sizes` | Add sizes to a product draft |
| `ecommerce_remove-draft-sizes` | Remove sizes from a product draft |
| `ecommerce_apply-draft-to-product` | Apply draft changes to a product |
| `ecommerce_get-customization-pricing` | Get pricing for product customization options |
### Brand & Design Assets
Pull a brand's look and artwork into a form you can drop straight into products and your storefront.
| Tool | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| `brand_from_url` | Build a brand profile — logo, colors, fonts, and a summary — by scraping a brand's website |
| `brand_analyze` | Analyze a logo or brand-sheet image for its colors, fonts, and artwork |
| `brand_analyze_start` | Start an asynchronous brand analysis of an image |
| `brand_analyze_status` | Check the status of a brand analysis job |
| `brand_extract_assets` | Extract clean transparent-PNG logos and artwork from an analyzed brand sheet |
| `brand_extract_assets_start` | Start an asynchronous asset extraction |
| `brand_extract_assets_status` | Check the status of an asset extraction job |
| `image_remove_background` | Remove the background from an image, returning a transparent PNG |
## Get Human Help
The MCP server includes a built-in `omni_escalate` tool that hands your conversation off to Fourthwall's human support team when you need a person.
You can ask your assistant things like:
* *"Connect me with a human — I have a payout issue that isn't resolved"*
* *"Escalate this to Fourthwall support"*
Your assistant passes along a summary of the conversation so the support team has the context they need to help quickly.
## Troubleshooting
**I can't connect or authenticate**
* Make sure you have a Fourthwall account with dashboard access
* Try disconnecting and reconnecting the MCP server in your client
* Check that your client supports the Streamable HTTP transport
**Tools are missing or unavailable**
* Make sure you've selected a shop after authenticating
* Reconnect the MCP server if tools don't appear after login
**I'm getting errors on tool calls**
* Verify you have the correct permissions for the action (e.g., Super Admin or Manager for some operations)
* Check that the entity IDs you're referencing exist in your shop
* Ask your assistant to escalate persistent issues to Fourthwall support — include what you were trying to do
## Related Resources
Documentation files and MCP server for AI code editors
RESTful API for direct programmatic access
API key and OAuth authentication guides
Join our Discord for help and discussions