Fourthwall MCP Server & CLI

What you can ask it

Ask for a bounded shop task, then review any change before execution:

• List the first 25 products in the intended shop and report their state and availability separately.
• Read this order and check the native fulfillment contract before preparing a tracking update.
• Review these exact product availability changes, then execute only the batch I approve.
• Export up to ten pages of order metadata into a new private file and report continuation.
• Prepare a hidden digital product from this reviewed native payload. Do not publish it implicitly.
• Upload this local image from a private receipt, then show the separate registration step.

These prompts name implemented operations. The terminal animation illustrates a reviewed workflow, rather than an authenticated shop recording.

Set up your account

A Fourthwall SUPER ADMIN can create shop API credentials in Settings > For Developers. Follow Fourthwall authentication. Shop Basic credentials grant full shop access; never describe them as a read-only key.

Choose exactly one private source: FOURTHWALL_USERNAME and FOURTHWALL_PASSWORD, an existing FOURTHWALL_ACCESS_TOKEN, or FOURTHWALL_CREDENTIALS_FILE. OAuth permission comes from the provider. This package does not implement consent, exchange or refresh.

{"username":"YOUR_PRIVATE_SHOP_API_USERNAME","password":"YOUR_PRIVATE_SHOP_API_PASSWORD"}

Alternatively store only an already-issued access_token in that file. Replace placeholders only privately, restrict the file and parent directory, and adapt paths for the actual OS/runtime.

The credential file is a JSON object containing either username/password or access_token. It must be an absolute regular non-symlink file, at most 64 KiB, outside repositories. On POSIX the process user must own it and permissions must be owner-only, normally 0600; restrict Windows ACLs separately. Never paste credentials into chat, command transcripts, issues, payloads or project configuration.

fourthwall-cli login
fourthwall-cli list-accounts --agent
fourthwall-cli doctor
fourthwall-cli doctor --network

Login prints instructions. Doctor checks local profiles and policy; the deliberate network option reads the current shop and validates its id. One successful read does not prove every permission, every task or resource ownership. File credentials are cached for the process: restart clients after rotating or revoking them.

Install

Install Node 22+ in the runtime that launches the server. Use the complete INSTALL.md for Codex, Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and all three desktop OSes.

npm install -g @thenavidm/fourthwall-mcp-cli@latest
fourthwall-cli --version
fourthwall-cli tools
fourthwall-cli schema list-products

After configuring credentials privately, register the local server in Codex:

codex mcp add fourthwall -- npx -y @thenavidm/fourthwall-mcp-cli@latest
codex mcp list

The MCP executable speaks stdio; it is not a hosted URL. The desktop extension is fourthwall-2.0.0.mcpb. Manual installation and updates use the host's supported extension screen. Choose one auth source, leave unused inputs empty and reconnect. GUI installation and authenticated provider tasks require their own validation.

More local client setup

OpenCode

Merge this into your private user config, following OpenCode's MCP docs. Reconnect and inspect the server status.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fourthwall": {
      "type": "local",
      "command": ["npx", "-y", "@thenavidm/fourthwall-mcp-cli@latest"],
      "enabled": true,
      "environment": {"FOURTHWALL_CREDENTIALS_FILE": "/absolute/private/fourthwall.json"}
    }
  }
}

Copilot CLI

After private runtime setup, use Copilot CLI's documented registration:

copilot mcp add fourthwall --env FOURTHWALL_CREDENTIALS_FILE=/absolute/private/fourthwall.json -- npx -y @thenavidm/fourthwall-mcp-cli@latest
copilot mcp get fourthwall

Registration stores the private file path in user configuration; do not put actual credentials in the command or repository.

OpenClaw

Use the saved-server registry in an eligible runtime, following OpenClaw's MCP reference:

openclaw mcp add fourthwall --command npx --arg -y --arg @thenavidm/fourthwall-mcp-cli@latest --env FOURTHWALL_CREDENTIALS_FILE=/absolute/private/fourthwall.json
openclaw mcp doctor fourthwall --probe

Configure paths in the process where the server actually runs. Runtime projection and trust policy remain client-specific; a saved entry is not proof of a successful provider call.

Antigravity

Follow Google's current custom-server instructions: open MCP Servers, Manage MCP Servers, then View raw config. Merge the Claude Desktop manual mcpServers block above. Current global config is ~/.gemini/config/mcp_config.json; project .agents/mcp_config.json must never contain secrets. The local stdio command/args/env form applies. Reconnect and inspect tools.

Hermes

Merge this into your private ~/.hermes/config.yaml, following Hermes MCP configuration:

mcp_servers:
  fourthwall:
    command: "npx"
    args: ["-y", "@thenavidm/fourthwall-mcp-cli@latest"]
    env:
      FOURTHWALL_CREDENTIALS_FILE: "/absolute/private/fourthwall.json"

Restart the agent and inspect available tools. An agent shell can also use fourthwall-cli directly with the shipped SKILL.md; installing npm does not automatically register the skill.

Output and exit codes

Both binaries use the same schemas, handlers, validation and confirmation guard. --json prints JSON, --compact prints a single line, and --agent gives compact output for an agent. --select projects requested output fields. Errors go to stderr. --yes suppresses interactive presentation; it never replaces --confirm.

fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-shop --account intended-shop --json
fourthwall-cli schema create-promotion

Tool path/query snake_case arguments become dash flags. Native body fields retain their exact camelCase flags, such as --fileName and --contentType; inspect --help instead of guessing a spelling. Objects and arrays use JSON. Use a private --payload-file for larger native bodies. Do not mix payload, payload-file and flat body fields.

Which surface and what each costs

Use CLI for scripts, shell agents and selected tasks. Use MCP where your app discovers tools and calls them directly. Both surfaces reach the same 86 tasks and enforce the same approval policy.

No matched completed Codex task/token measurement has been collected for this integration. Counts, schema characters, discovery costs and another integration's benchmark are not task savings. A fair comparison must record equivalent inputs, current client/model, permissions, successful native outcomes, errors/retries and total tokens. Software is free under AGPL-3.0; provider fees and plans remain separate.

Tools

49 reads and 37 confirmed effects. All 86 tasks follow below; nested native JSON fields come from the selected reviewed schema.

get_webhook

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Get a webhook

CLI: fourthwall-cli get-webhook. Policy: read.

Native: GET /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

update_webhook

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Update a webhook

CLI: fourthwall-cli update-webhook. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

delete_webhook

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Delete a webhook

CLI: fourthwall-cli delete-webhook. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

start_streaming

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Sets streaming status to started for specified services

CLI: fourthwall-cli start-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/start. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

end_streaming

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Sets streaming status to ended for specified services

CLI: fourthwall-cli end-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/end. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

get_public_token

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Returns an existing public token for the shop, or creates a new one if none exists

CLI: fourthwall-cli get-public-token. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/public-token. Current source.

get_promotion

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Returns a promotion by id

CLI: fourthwall-cli get-promotion. Policy: read.

Native: GET /open-api/v1.0/promotions/{promotionId}. Current source.

update_promotion

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Updates an existing promotion's configuration. Only provided fields are updated; omitted fields remain unchanged. Status changes (activate/deactivate) are part of the same update call.

CLI: fourthwall-cli update-promotion. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/promotions/{promotionId}. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

update_product_state

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Transitions the product between PUBLIC and HIDDEN. Use DELETE /products/{productId} to archive — ARCHIVED is not reachable here. The sold-out (available) flag is preserved; flip it via PUT /products/{productId}/availability. Idempotent: no-op if the product is already in the requested state.

CLI: fourthwall-cli update-product-state. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/state. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

toggle_product_availability

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Updates a product (offer) availability

CLI: fourthwall-cli toggle-product-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/availability. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

mark_download_complete

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Marks digital download as downloaded. If no downloads exist for a digital order and defaultFileUrl is provided in the request body, creates a download with that URL and marks it as downloaded.

CLI: fourthwall-cli mark-download-complete. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/order/{orderId}/downloaded. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

finish_giveaway

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Finish giveaway and select winners

CLI: fourthwall-cli finish-giveaway. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaways/{id}/finish/twitch. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

create_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Creates a new giveaway or updates existing one

CLI: fourthwall-cli create-giveaway-checkout. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaway-checkout. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

disable_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

disables a giveaway config

CLI: fourthwall-cli disable-giveaway-checkout. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/giveaways/giveaway-checkout. Current source.

finish_giveaway_draw

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Finish draw and select winners

CLI: fourthwall-cli finish-giveaway-draw. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/draw/{id}/finish. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

get_gifting_config

Returns the calling shop's saved gifting rules. Returns a default-shaped config when none is persisted yet.

CLI: fourthwall-cli get-gifting-config. Policy: read.

Native: GET /open-api/v1.0/gifting/config. Current source.

update_gifting_config

Writes the four creator-controlled gifting rule fields. Validation (duration 20-180s, valid shipping/products) and the one-platform-per-shop mutex are enforced server-side. Upserts: a first-ever PUT materializes the config row.

CLI: fourthwall-cli update-gifting-config. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/config. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

update_collection

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Updates collection name, description, and/or product list

CLI: fourthwall-cli update-collection. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

get_collection_products

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Returns paginated products in a collection with optional status filtering. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli get-collection-products. Policy: read.

Native: GET /open-api/v1.0/collections/{collectionId}/products. Current source.

update_collection_products

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Sets the full list of product IDs in the collection

CLI: fourthwall-cli update-collection-products. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/products. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

update_collection_availability

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Toggle collection availability (available/unavailable)

CLI: fourthwall-cli update-collection-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/availability. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

list_webhooks

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Get webhooks

CLI: fourthwall-cli list-webhooks. Policy: read.

Native: GET /open-api/v1.0/webhooks. Current source.

create_webhook

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Create a webhook

CLI: fourthwall-cli create-webhook. Policy: explicit confirmation.

Native: POST /open-api/v1.0/webhooks. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

list_promotions

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Returns all promotions. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-promotions. Policy: read.

Native: GET /open-api/v1.0/promotions. Current source.

create_promotion

Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/rate-limiting).

Creates a promotion

CLI: fourthwall-cli create-promotion. Policy: explicit confirmation.

Native: POST /open-api/v1.0/promotions. Current source.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.