MCP Server - Fourthwall Developer Docs

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”
“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)

Open Claude settings and navigate to Connectors
Select Add custom connector
Enter name: Fourthwall
Enter URL: https://mcp.fourthwall.com
Select Add
You’ll be prompted to log in with your Fourthwall account

Run in your terminal:

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:

codex mcp add fourthwall --url https://mcp.fourthwall.com

Then start the OAuth flow to log in with your Fourthwall account:

codex mcp login fourthwall

Or add the server to ~/.codex/config.toml by hand and run codex mcp login fourthwall:

[mcp_servers.fourthwall]
url = "https://mcp.fourthwall.com"

Open command palette (Cmd+Shift+P / Ctrl+Shift+P)
Search for Open MCP settings
Add to your mcp.json:

{
  "mcpServers": {
    "fourthwall": {
      "url": "https://mcp.fourthwall.com"
    }
  }
}

Open command palette (Cmd+Shift+P / Ctrl+Shift+P)
Search for MCP: Add Server
Select HTTP
Enter URL: https://mcp.fourthwall.com
Enter name: fourthwall

Add to your ~/.gemini/settings.json:

{
  "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:

Your AI client opens a browser window to Fourthwall’s login page
You log in with your existing Fourthwall credentials
You select which shop to connect (if you manage multiple shops)
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 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

LLM Support

Documentation files and MCP server for AI code editors

Platform API

RESTful API for direct programmatic access

Authentication

API key and OAuth authentication guides

Community

Join our Discord for help and discussions

​What You Can Do

​Connect to the MCP Server

​Authentication

​Available Tools

​Search & Knowledge

​Products & Catalog

​Orders & Fulfillment

​Collections

​Promotions

​Gift Cards & Giveaways

​Analytics & Reports

​Memberships

​Integrations & Shipping

​Shop & Account

​Write & Management Tools

​Products

​Collections

​Promotions

​Orders & Fulfillment

​Gift Cards & Giveaways

​Samples & Shop

​Product Design

​Brand & Design Assets

​Get Human Help

​Troubleshooting

​Related Resources

LLM Support

Platform API

Authentication

Community

What You Can Do

Connect to the MCP Server

Authentication

Available Tools

Search & Knowledge

Products & Catalog

Orders & Fulfillment

Collections

Promotions

Gift Cards & Giveaways

Analytics & Reports

Memberships

Integrations & Shipping

Shop & Account

Write & Management Tools

Products

Collections

Promotions

Orders & Fulfillment

Gift Cards & Giveaways

Samples & Shop

Product Design

Brand & Design Assets

Get Human Help

Troubleshooting

Related Resources