> ## 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 data — products, orders, promotions, collections, analytics, and more.

## What You Can Do

Once connected, you can ask your AI assistant things like:

* *"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"*

## Connect to the MCP Server

**Server URL:** `https://mcp.fourthwall.com` (Streamable HTTP)

<Tabs>
  <Tab title="Claude Desktop">
    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
  </Tab>

  <Tab title="Claude Code">
    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.
  </Tab>

  <Tab title="Cursor">
    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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    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`
  </Tab>

  <Tab title="Gemini CLI">
    Add to your `~/.gemini/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "fourthwall": {
          "httpUrl": "https://mcp.fourthwall.com"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other Clients">
    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)
  </Tab>
</Tabs>

## 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 provides read-only access to your shop data across the following categories.

### 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                                  |

### 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     |

### 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 |

### 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 |

### 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    |

### 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 |

## Send Feedback

The MCP server includes a built-in `send-feedback` tool that lets you report issues or request features directly from your AI conversation.

You can ask your assistant things like:

* *"Send feedback that the orders search is slow when filtering by date range"*
* *"Submit a feature request for bulk order export"*

Your feedback goes directly to the Fourthwall team along with relevant conversation context, so we can understand and address it 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
* Use `send-feedback` to report persistent issues — include what you were trying to do

## Related Resources

<CardGroup cols={2}>
  <Card title="LLM Support" icon="robot" href="/ai/llm-support">
    Documentation files and MCP server for AI code editors
  </Card>

  <Card title="Platform API" icon="code" href="/guides/overview">
    RESTful API for direct programmatic access
  </Card>

  <Card title="Authentication" icon="lock" href="/guides/authentication">
    API key and OAuth authentication guides
  </Card>

  <Card title="Community" icon="discord" href="/resources/community">
    Join our Discord for help and discussions
  </Card>
</CardGroup>