Becomy MCP Server

Overview

The Becomy MCP server (v0.15.0) exposes tools that let an LLM read and edit your Shopify-compatible theme (sections, templates, liquid files), query store commerce data (products, collections, orders, coupons), manage the product catalog (list, stats, bulk status updates, URL import), fetch analytics chart data (orders, visits, conversion, product creations, stock movements), report AI credit balance and consumption history, build marketing automation scenarios (customer journey flows, segments, analytics, and integration status), orchestrate dated marketing campaigns (canvas, visuals, social, email), run the store's AliExpress dropshipping activity (marketplace search, import, stock sync, supplier orders), and customize storefront themes via the Dawn editor.

For flow concepts (triggers, compliance, integrations, segments), see the Marketing Automations guide. For campaign canvas concepts (timeline, populate, launch), see the Campaigns guide.

Two transports are supported:

HTTP (streamable) — public endpoint on your store domain at /mcp. Best for remote agents and hosted LLMs (OpenAI, Anthropic, Cursor, etc.).
Stdio — local rake task for development. Best for Cursor when running the Rails app on the same machine.

To create a brand-new store from an agent (no subdomain yet), use the Platform MCP sign_up_store tool on the apex host, then switch to the returned store MCP URL with the issued Bearer token.

In-app agents: the Becomy Studio copilot, theme editor, marketing flow editor, campaign canvas editor, and strategy advisor include AI assistant panels that call the same MCP tool classes via RubyLLM + OpenAI. Configure OPENAI_API_KEY on the server to enable them. Conversations are persisted with multi-turn memory and safety tagging. Chart tools return structured JSON; the Studio copilot renders graphs inline in the chat UI.

Platform MCP (signup)

Store MCP lives on a merchant subdomain (https://{store}.becomy.com/mcp) and needs an existing store + mcp_api_token. To create a store from an agent (no subdomain yet), use the apex Platform MCP instead.

Endpoint (dev): http://localhost:5000/mcp on an apex / reserved host (e.g. localhost, not {store}.localhost).
Endpoint (prod): https://becomy.com/mcp (or your platform apex host).
Server name: becomy-platform · version 0.1.0
Auth: none for sign_up_store. After signup, authenticate on the returned store MCP URL with Bearer mcp_api_token.
Abuse limits: rate-limited by IP and email (defaults: 12/hour and 24/day per IP and per email; override with PLATFORM_SIGNUP_HOURLY_LIMIT / PLATFORM_SIGNUP_DAILY_LIMIT).
Controller / server: app/controllers/platform_mcp_controller.rb, app/mcp/platform_mcp_server.rb

Server instructions (sent at MCP initialize)

Becomy Platform MCP: create merchant stores without an existing store subdomain. Signup flow: 1. Call `sign_up_store` with email, password, domain_name (and optional first_name/last_name). 2. Use the returned `mcp_api_token` and `mcp_url` (http://{domain}.{app_domain}/mcp) for all subsequent store tools on the Becomy store MCP (`becomy`). 3. In development, email confirmation is skipped by default so Studio is usable immediately. In production, email confirmation is always required (`skip_confirmation` is ignored). 4. Signup is rate-limited by IP and email to prevent serial abuse. After signup (on the store MCP, with Bearer token): - Prefer `create_product` with status "active", price, and available so the storefront is sellable (default variants are archived / 0 stock otherwise). - Organize with `create_collections` / `update_collection` (product_ids). - Brand the Dawn theme with menus, assets, section/block settings; `publish_theme` only applies to drafts. Full merchant docs: /docs/mcp#platform-mcp Never put store secrets in chat logs. Prefer Bearer auth on the per-store MCP URL after signup.

Tool: `sign_up_store`

Argument	Required	Description
`email`	yes	Merchant email (Owner + AdminUser)
`password`	yes	Admin password (min 8 chars)
`domain_name`	yes	Store slug, e.g. `xdrone` → `xdrone.localhost` / `xdrone.becomy.com`
`first_name` / `last_name`	no	Admin display name
`skip_confirmation`	no	Non-production only (default `true` outside production). Ignored in production — email confirmation is always required.

Successful response includes status, store_id, domain_name, email, mcp_api_token, mcp_url, storefront_url, studio_url, sign_in_url, confirmed, and confirmation_required.

Agent bootstrap (recommended order):

Call apex sign_up_store.
Switch HTTP client to {mcp_url} with Authorization: Bearer {mcp_api_token}.
Brand & catalog: update_store_brief → create_collections (optional product_ids) → create_product with status: "active", price, available → attach_product_media → update_collection for Featured / category membership.
Theme: upsert_store_menu, upload_store_asset + update_section_settings / update_block_settings, update_theme_settings. Dawn is installed as main on signup — publish_theme is only for draft themes.

Cursor — Platform MCP config

Add a second server entry for signup (no Bearer). Keep the store server for day-to-day tools.

{ "mcpServers": { "becomy-platform": { "url": "http://localhost:5000/mcp" }, "becomy": { "url": "http://YOUR-STORE.localhost:5000/mcp", "headers": { "Authorization": "Bearer YOUR_MCP_API_TOKEN" } } } }

Security: never paste mcp_api_token or passwords into chat logs or commits. Prefer env vars / Cursor secret headers after signup. In production, confirm the admin email before Studio sign-in; do not rely on skip_confirmation.

Authentication

Store MCP (https://{store}.…/mcp): each store has a unique MCP API token. Send it on every HTTP request:

Authorization: Bearer YOUR_MCP_API_TOKEN

Platform MCP (apex /mcp, signup only): no Bearer token for sign_up_store. The response returns a fresh mcp_api_token for the new store — see Platform MCP. Copy it immediately; Becomy stores only a hash.

Get your token

Sign in to your store Studio, then open Settings → MCP API token to rotate and copy a new token (shown once).

Rotate a token

In Studio: Settings → Rotate token. The new plaintext is shown once in a banner.

# Rails console (returns plaintext once; DB keeps only the digest) raw = store.regenerate_mcp_api_token! puts raw

Admin users who are signed in to the store can also call /mcp without a Bearer token (browser session). External agents should always use the API token.

HTTP transport

The MCP server uses the streamable HTTP transport (stateless mode) from the official mcp Ruby gem.

Method	Path	Purpose
`POST`	`/mcp`	Send JSON-RPC requests (`initialize`, `tools/list`, `tools/call`, …)
`GET`	`/mcp`	Open SSE stream (session mode; optional)
`DELETE`	`/mcp`	Close an SSE session

Endpoint

https://{your-store-domain}/mcp

Required headers

Header	Value
`Authorization`	`Bearer <mcp_api_token>`
`Content-Type`	`application/json` (POST)
`Accept`	`application/json, text/event-stream` (POST)

Initialize (handshake)

curl -X POST "https://{your-store-domain}/mcp" \ -H "Authorization: Bearer YOUR_MCP_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0.0" } } }'

List tools

curl -X POST "https://{your-store-domain}/mcp" \ -H "Authorization: Bearer YOUR_MCP_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }'

Call a tool

curl -X POST "https://{your-store-domain}/mcp" \ -H "Authorization: Bearer YOUR_MCP_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_products", "arguments": { "limit": 5 } } }'

Stdio transport (local)

For local development, run the MCP server as a subprocess over stdin/stdout. Cursor and other MCP clients spawn this command automatically.

STORE_DOMAIN=your-store rake mcp:theme_server

STORE_DOMAIN must match the store’s domain_name in the database. The server uses that store’s editing theme (draft if present, otherwise main).

Stdio mode does not require an API token — it runs with full access to the store specified by STORE_DOMAIN. Only use it on trusted machines.

Cursor setup

Option A — Remote HTTP (recommended for production)

Add to your Cursor MCP config (~/.cursor/mcp.json or project .cursor/mcp.json):

{ "mcpServers": { "becomy": { "url": "https://{your-store-domain}/mcp", "headers": { "Authorization": "Bearer YOUR_MCP_API_TOKEN" } } } }

To create stores from Cursor, also add the apex Platform MCP entry (becomy-platform, no Bearer).

Option B — Local stdio (development)

{ "mcpServers": { "becomy": { "command": "bundle", "args": ["exec", "rake", "mcp:theme_server"], "env": { "STORE_DOMAIN": "your-store" }, "cwd": "/path/to/shopeo" } } }

Restart Cursor after saving. The agent can then call theme and commerce tools while you edit.

Tools reference

Server name: becomy · version 0.15.0 · Platform signup: becomy-platform v0.1.0

Theme tools

Operate on the store’s editing theme (draft copy when present).

Tool	Description	Key arguments
`list_theme_files`	List theme files (layout, templates, sections, snippets, config, locales, assets)	`prefix` (optional, e.g. `sections/`)
`read_theme_file`	Read a theme file by path	`path` (required)
`write_theme_file`	Create or replace a text theme file	`path`, `content`
`update_section_settings`	Merge section-level settings (not block text)	`section_id`, `settings`, `template`
`update_block_settings`	Merge block settings (announcement text, slides, etc.)	`section_id`, `block_id`, `settings`, `template`
`update_theme_settings`	Merge global theme settings (colors, typography, page width)	`settings` (object of setting ids → values)
`get_section_schema`	Return {% schema %} and live instance (settings, blocks, storage path)	`section_id` and/or `section_type`, `template`
`add_section_to_template`	Add a section type to a JSON template	`section_type`, `template`, `position`
`remove_section_from_template`	Remove a section instance from a JSON template	`section_id`, `template`
`update_section_order`	Reorder sections in a JSON template	`order` (array), `template`
`update_layout_section_order`	Reorder sections in a layout group (header-group, footer-group)	`group`, `order` (array)
`add_block`	Add a block to a section with schema defaults	`section_id`, `block_type`, `template`, `position`
`remove_block`	Remove a block from a section	`section_id`, `block_id`, `template`
`update_block_order`	Reorder blocks inside a section	`section_id`, `order` (array), `template`
`list_store_menus`	List store navigation menus with nested items	`handle` (optional filter)
`upsert_store_menu`	Create or replace a menu and nested dropdown items	`handle`, `title` (optional), `items` (nested)
`list_store_assets`	List store image/file library URLs for image_picker settings	`category`, `query`, `limit`
`upload_store_asset`	Upload image/PDF to the store library from a public URL or base64	`url` or `content_base64` + `filename`, optional `name`
`publish_theme`	Publish draft theme to live storefront (requires agent confirmation)	—
`render_section_preview`	Render one section to HTML	`section_id`, `template`

Commerce tools (read-only)

Tool	Description	Key arguments
`list_products`	List products with search, status tabs, sort and pagination	`query`, `status` (all/active/offline/out_of_stock/archive), `sort`, `direction`, `page`, `per_page`
`get_product`	Full product detail (variants, media, vendor, stock)	`product_id` (required)
`get_product_stats`	Product counts by tab (all, active, offline, out_of_stock, archive)	—
`list_collections`	List collections	`limit`
`list_orders`	List orders with search, status tabs, date range and pagination	`query`, `status`, `payment_status`, `date_from`, `date_to`, `page`, `per_page`
`get_order`	Full order detail (customer, addresses, line items, tracking)	`order_id` (required)
`get_order_stats`	Order counts by tab (all, open, unfulfilled, fulfilled, unpaid, archived, refunded)	—
`list_coupons`	List store coupon codes (for grant-coupon steps)	`limit` (default 50)
`get_store_chart`	Return time-series chart data for store analytics (JSON). Used by in-app agents to render graphs in the Studio copilot.	`metric` (required), `range` (required), `chart_type` (optional: `area`, `line`, `bar`), `product_id` or `product_title` (optional — `stock_movements` only)
`get_ai_credit_balance`	Remaining prepaid AI credit balance, low-balance flag and lifetime purchased/consumed totals. Becomy meters AI usage in prepaid credits (not a fixed token quota), so report the credit balance as the “remaining plan” figure.	—
`get_ai_usage_history`	AI consumption bucketed over time: credits spent and input/output token counts per period, plus totals.	`period` (required: `hour`, `day`, `week`, `month`), `from`, `to` (optional ISO8601/YYYY-MM-DD; sensible default window per period)

`get_ai_usage_history` periods

Granularity buckets returned by the tool, with their default look-back window when from/to are omitted: hour (last 24 h), day (last 30 days), week (last 12 weeks), month (last 12 months). Each bucket reports period_start, credits, input_tokens, output_tokens and total_tokens.

Example response (`get_ai_usage_history`)

{ "period": "day", "from": "2026-05-13T00:00:00Z", "to": "2026-06-12T00:00:00Z", "total_credits": 42.5, "total_tokens": 18230, "buckets": [ { "period_start": "2026-06-11T00:00:00Z", "credits": 12.0, "input_tokens": 4200, "output_tokens": 1310, "total_tokens": 5510 } ] }

`get_store_chart` metrics

Metric	Description	Notes
`orders`	Daily order count	Store orders by `created_at`
`visits`	Daily storefront visits	Unique sessions from `daily_visits`
`conversion`	Daily conversion rate	Derived from visits and orders
`product_creations`	Daily new products created	Aliases: `products`, `products_created`
`stock_movements`	Inventory movement history	Three series: movement count, units in, units out. Filter globally or per product with `product_id` / `product_title`. Units in/out are reliable for order-linked movements; manual adjustments are counted in movement count only.

`get_store_chart` ranges

current_week, last_week, days_ago_7, days_ago_14, days_ago_21

Example response

{ "chart": { "id": "orders-days_ago_7", "title": "Orders — Last 7 days", "type": "area", "metric": "orders", "range": "days_ago_7", "labels": ["Mon, Jun 02, 2026", "Tue, Jun 03, 2026"], "datasets": [ { "label": "Orders", "data": [3, 5] } ], "summary": { "total": 8, "points": 2 } } }

stock_movements returns multiple datasets (Movements, Units in, Units out). Default chart type is bar for stock movements; other metrics default to area.

Commerce tools (write)

Available to external MCP clients and the in-app commerce agent. Destructive actions may require confirmation in the UI. See also the Product catalog guide.

Tool	Description	Key arguments
`create_product`	Create a product with a default variant. Defaults to `offline`. Pass `status: "active"`, `price`, and `available` to publish a sellable SKU (unarchives the default variant, sets stock, syncs `products.price` for the storefront).	`title`, optional `price`, `available`, `status`
`update_product`	Update title/description/status/price/stock. Setting `status: "active"` or `available` unarchives the default variant. `price` also updates `products.price` (Liquid uses that field). Optional description cleanup via `strip_images` / `strip_sections`.	`product_id` (optional on product page), `title`, `description`, `price`, `available`, `status`, `strip_images`, `strip_sections`
`update_product_page_details`	Write Product page details accordion fields (custom metafields)	`details` (e.g. `shipping_returns`), optional `product_id`
`attach_product_media`	Import image URLs into the product gallery (optionally from description HTML)	`urls` and/or `from_description`, `remove_from_description`, `strip_sections`
`set_product_variants`	Replace a product's variant matrix from option groups (Color × Size…); every combination is generated	`options` (array of {name, values}), optional `product_id`, `price`, `available`, `sku_prefix` — requires confirmation in-app
`set_variant_image`	Assign a product gallery image to a specific variant	`variant_id`, `attachment_id`, optional `product_id`
`archive_product`	Set a product offline or archived	`product_id`, `status` (archive/offline) — requires confirmation in-app
`bulk_update_product_status`	Update status for multiple products at once	`product_ids` (array), `status` (active, offline, archive, out_of_stock)
`delete_product`	Permanently delete a product	`product_id` — requires confirmation in-app
`import_product_from_url`	Import a product from a public URL (async job). Extraction is hybrid: structured data (JSON-LD/Shopify), then the domain's visual import mapping when ready, then LLM fallback for missing fields. Returns an `import_id`.	`url` — requires confirmation in-app
`get_product_import_status`	Track an async import: status, `product_id` when completed, `extraction_source` (structured/mapping/llm/mixed), error message	`import_id`
`create_collections`	Create multiple manual collections in one call (existing titles are skipped). Optional `product_ids` per collection.	`collections` (array of {title, description, product_ids?}) — requires confirmation in-app
`update_collection`	Update a collection title/description and optionally replace its product membership	`collection_id`, `title`, `description`, `product_ids`
`generate_creative_media`	Launch Creative Studio image/video (hero banners, collection visuals, icons, Seedance clips). Poll with `get_creative_generation_status`, then `apply_creative_generation`.	`prompt`, `kind` (image\|video), `model`, `recipe_key`, `product_id`, `duration_seconds`, `aspect_ratio` (16:9\|9:16\|1:1, video)
`apply_creative_generation`	Wire a completed generation output into Dawn section settings (`image_banner.background_video_url`, `video.mp4_url`, image pickers…).	`generation_id`, `section_id`, `setting_key`, optional `template`, `also_set`
`get_creative_generation_status`	Poll a creative generation; returns `output_urls` when completed	`generation_id`
`create_store_page`	Create/update a CMS page (Mentions légales, CGV, Qui sommes-nous…)	`title`, `slug`, `html`, optional `page_description`
`create_product_review`	Seed a storefront product review	`product_id`, `author_name`, `rating`, `body`
`update_order_status`	Change order fulfillment status	`order_id`, `status` (open, unfulfilled, fulfilled, refunded, close)
`update_order_tracking`	Set shipping tracking number	`order_id`, `tracking_number`
`update_order_notes`	Update merchant notes on an order	`order_id`, `notes`
`create_draft_order`	Create a draft order with customer and line items	`email`, `line_items` (array of {variant_id, quantity})

Carnet Becomy (journal) tools

Read and write the merchant Carnet Becomy (personalized letters, replies, spontaneous notes to the team). Messages are read by the entire Becomy team, are not public, and are not a support channel. Studio UI: /admin/studio/profile and /admin/studio/journal.

Tool	Description	Key arguments
`list_becomy_journal`	Current Becomy letter + reverse-chronological timeline with excerpts	`limit` (optional, default 20)
`get_becomy_journal_entry`	Full text of one entry (letter, reply, or note)	`entry_id`
`write_to_becomy`	Send a spontaneous message to the Becomy team (max 3/month)	`body`
`reply_to_becomy_letter`	Reply once to a Becomy letter (24h edit window)	`letter_id`, `body`
`update_becomy_journal_entry`	Edit a reply or note within 24 hours of sending	`entry_id`, `body`

Onboarding tools

Power the guided store setup: merchant brief, generated setup plan, and task tracking. Used by the in-app onboarding agent and available to external MCP clients.

Tool	Description	Key arguments
`get_store_brief`	Return the merchant onboarding brief (project type, market, products, pricing, acquisition…) and which sections are still empty	—
`update_store_brief`	Save interview answers into the brief (deep-merged): market, products, inspiration, pricing, dreams, acquisition…	brief section objects (e.g. `market`, `products`, `dreams`) — requires confirmation in-app
`generate_setup_plan`	Generate or regenerate the store setup plan from the brief (completed tasks are preserved; requires a complete brief)	— requires confirmation in-app
`get_setup_plan`	Return the active setup plan: phases, tasks (status, due dates, deep links), milestones and progress	—
`update_task_status`	Mark a setup plan task as done, pending or skipped	`task_id`, `status` (`done`/`pending`/`skipped`)

Planning calendar tools

Read and manage the unified Planning calendar: every dated event of the store, manual milestones/goals, retail-moment recipes and scheduled publications.

Tool	Description	Key arguments
`get_calendar_events`	All dated events for a range: milestones, goals, tasks, campaign launches, coupon start/end, gift card expirations, scheduled publications, custom events, real-world events	`from`, `to` (YYYY-MM-DD, default next 60 days), `types` (optional filter)
`create_calendar_event`	Add a free-form event to the calendar (photo shoot, stock arrival…)	`title`, `starts_on`, `ends_on`, `notes`
`delete_calendar_event`	Delete a merchant custom event	`event_id`
`upsert_milestone`	Create or update a milestone (key project date); close it with status reached/missed	`milestone_id` (omit to create), `title`, `due_on`, `status`
`upsert_goal`	Create or update a measurable goal (orders, revenue, catalog size, custom) with live progress	`goal_id` (omit to create), `title`, `metric`, `target_value`, `target_date`, `status`
`list_calendar_recipes`	Upcoming retail moments (sales, Black Friday, Christmas…) carrying a preparation recipe, with applied state	`horizon_days` (default 60)
`apply_calendar_recipe`	Add the dated preparation tasks + milestone of a retail moment to the plan (idempotent)	`external_key` (e.g. `black_friday_2026`)
`schedule_publication`	Schedule (or cancel) the automatic publication of a product or collection at a date	`kind` (`product`/`collection`), `id`, `publish_at` (ISO datetime or null)

Marketing automation tools

Build and manage customer journey scenarios (same engine as the marketing automations guide). Graph saves support segments, entry rules, scheduled activation, A/B winner mode, and send-time delays on delay steps.

Tool	Description	Key arguments
`list_marketing_scenarios`	List scenarios with enrollment stats	`status` (optional: draft, active, paused)
`get_marketing_scenario`	Full scenario graph in editor format	`scenario_id`
`create_marketing_scenario`	Create a new draft scenario	`name`, `trigger_type`
`save_marketing_scenario_graph`	Save steps, edges, trigger config, scheduled activation	`scenario_id`, `graph` — graph may include `trigger_config.segment_id`, `entry_rules` (min_cart_value, tags), `scheduled_activate_at`, step configs for A/B winner mode and `send_at_hour` on delays
`duplicate_marketing_scenario`	Clone a scenario with all steps and edges (new draft)	`scenario_id`
`activate_marketing_scenario`	Activate scenario (go live)	`scenario_id`
`pause_marketing_scenario`	Pause scenario	`scenario_id`
`list_marketing_segments`	List audiences (living/saved-list) with rules and cached counts	—
`create_marketing_segment`	Create an audience (preset, living rules, or saved list + emails)	`name`, optional `preset`, `segment_kind`, `rules_json`, `emails`
`refresh_marketing_segment`	Recompute cached contact count for an audience	`segment_id`
`get_scenario_analytics`	Funnel, per-email open/click stats, revenue attribution	`scenario_id`
`get_store_integrations_status`	Email, SMS, and Stripe connection status (no API secrets returned)	—

Campaign tools

Dated marketing campaigns on the Campaign Desk — see campaigns guide. Workflow: create_campaign → populate_campaign or apply_ugc_flood_pack (deterministic UGC flood, same as the desk chip) → edit via save_campaign_graph → launch_campaign (preview with confirmed: false, then confirmed: true).

Tool	Description	Key arguments
`create_campaign`	Create draft campaign	`name`, `source_prompt`
`get_campaign`	Desk graph JSON	`campaign_id`
`populate_campaign`	Fill desk from prompt (async image/video)	`campaign_id`, `prompt`
`apply_ugc_flood_pack`	Apply UGC flood desk pack (chip parity)	`campaign_id`, `product_id`
`save_campaign_graph`	Persist cards and positions	`campaign_id`, `graph`
`get_campaign_status`	Poll card generation states	`campaign_id`
`launch_campaign`	Preview or execute launch	`campaign_id`, `confirmed`
`generate_campaign_image`	Regenerate visuals card	`campaign_id`, `prompt`
`generate_campaign_video`	Regenerate video card	`campaign_id`, `orientation`
`schedule_campaign_social_post`	Schedule social card post	`campaign_id`, `card_id`
`get_campaign_analytics`	KPI snapshot and ratios (revenue, orders, email, social, AI credit ROAS)	`campaign_id`
`get_generation_status`	Poll async image/video generation	`generation_id`

Tip: Call get_store_integrations_status before activating email-heavy scenarios — sends require a connected merchant email provider at /admin/integrations.

AliExpress dropshipping tools

Manage the store's AliExpress dropshipping activity — see the dropshipping guide. Most tools require the merchant to connect AliExpress once from Studio > Dropshipping (browser OAuth; it cannot be completed via MCP). Imported stock lives in the read-only virtual warehouse "AliExpress (synchronisé)" and is refreshed from the supplier automatically.

Tool	Description	Key arguments
`get_dropshipping_status`	Connection state, linked products by sync status, virtual warehouse stock summary, supplier orders	—
`search_aliexpress_products`	Search the AliExpress marketplace (bestseller feed when no query); flags already-imported products	`query`, `page`, `ship_to`, `sort`
`get_aliexpress_product`	Full product detail before import: SKUs, supplier prices, live stock, images	`external_product_id`, `ship_to`
`import_aliexpress_product`	Async import into the catalog (variants linked to AliExpress SKUs, x2 default markup); poll `get_product_import_status`	`external_product_id`, `ship_to`
`list_dropshipping_products`	Linked products with sync status, supplier cost vs selling price per variant, AliExpress URLs	`sync_status`, `page`
`sync_dropshipping_stocks`	Refresh stock/cost from AliExpress: one product inline, or all in background (auto every 6h)	`product_id` (optional)
`place_dropshipping_order`	Preview (`confirmed: false`) then place the supplier order on AliExpress shipped to the customer	`order_id`, `confirmed`
`get_dropshipping_order`	Supplier order status, tracking, carrier and AliExpress order links (auto-sync every 4h)	`order_id`, `sync`

Examples

Create a store from an agent (Platform MCP)

Call this on the apex host (http://localhost:5000/mcp), not on a store subdomain. Tool: sign_up_store — see Platform MCP.

{ "email": "owner@example.com", "password": "a-strong-password", "domain_name": "xdrone", "first_name": "Alex", "last_name": "Pilot" }

Then switch to the returned mcp_url with Authorization: Bearer {mcp_api_token} for all store tools below.

Create a sellable product (price + stock)

Tool: create_product

{ "title": "AeroX Cine 4K Drone", "price": 899, "available": 25, "status": "active" }

Without available / status: "active", the default variant stays archived with 0 stock (storefront shows sold out / €0). Prefer setting them in the same call.

Assign products to a collection

Tool: update_collection

{ "collection_id": 11, "title": "Drones", "description": "Ready-to-fly and cine drones", "product_ids": [65, 66, 75, 76] }

Or pass product_ids inside each item of create_collections. product_ids fully replaces membership when provided.

Change the homepage banner heading

Tool: update_section_settings

{ "template": "index", "section_id": "image_banner", "settings": { "heading": "Summer collection" } }

Change the announcement bar text (Dawn layout)

Dawn stores announcement text in a block inside sections/header-group.json, not in section-level settings. Use get_section_schema first to discover block_id and keys.

Tool: get_section_schema

{ "section_id": "announcement-bar" }

Tool: update_block_settings

{ "section_id": "announcement-bar", "block_id": "announcement-bar-0", "settings": { "text": "Livraison gratuite dès 50 €" } }

Change the primary theme color

Tool: update_theme_settings

{ "settings": { "primary_color": "#1a73e8" } }

Reorder homepage sections

Tool: update_section_order

{ "template": "index", "order": ["featured_products", "image_banner", "rich_text"] }

Move announcement bar below the header (Dawn layout)

Tool: update_layout_section_order

{ "group": "header-group", "order": ["header", "announcement-bar"] }

Add a slideshow slide

Tools: add_block then update_block_settings

{ "template": "index", "section_id": "slideshow", "block_type": "slide" }

{ "section_id": "slideshow", "block_id": "slide_2", "settings": { "heading": "New arrivals", "button_label": "Shop now" } }

Upload an image to the store library

Tool: upload_store_asset

{ "url": "https://cdn.example.com/hero-banner.jpg", "name": "Hero banner" }

Alternative with base64 bytes:

{ "content_base64": "iVBORw0KGgoAAAANSUhEUg…", "filename": "hero-banner.png", "content_type": "image/png" }

Set a banner image from the asset library

Tools: list_store_assets or upload_store_asset, then update_section_settings

{ "category": "image", "query": "hero" }

{ "template": "index", "section_id": "image_banner", "settings": { "image": "/rails/active_storage/blobs/…/hero.jpg" } }

Use the url from list_store_assets — do not invent URLs.

Publish the draft theme (go live)

Tool: publish_theme — requires explicit confirmation in the Studio copilot.

{}

Only call when the merchant asks to publish or go live. Replaces the current main theme.

Remove a section from the index template

Tool: remove_section_from_template

{ "template": "index", "section_id": "rich_text" }

Add a new section to the index template

Tool: add_section_to_template

{ "template": "index", "section_type": "featured-products" }

Read the product template

Tool: read_theme_file

{ "path": "templates/product.json" }

Ask the agent in the theme editor

Open /theme_editor and use the Agent panel in the sidebar. With OPENAI_API_KEY configured, the agent calls these tools automatically via tool-calling.

Check integrations before going live

Tool: get_store_integrations_status

{}

Returns status per provider (sendgrid, mailgun, twilio, stripe, etc.) without exposing secrets.

List segments for a targeted flow

Tool: list_marketing_segments

{}

Build a welcome email scenario

Tools: create_marketing_scenario then save_marketing_scenario_graph

{ "name": "Welcome series", "trigger_type": "customer_signed_up", "trigger_config": { "enrollment_policy": "once_per_contact", "require_consent": true }, "steps": [ { "key": "email-1", "kind": "action_email", "x": 320, "y": 200, "config": { "subject": "Welcome!", "body": "Hi {{ user.first_name }}..." } } ], "edges": [ { "from_key": "trigger", "to_key": "email-1", "branch": "default" } ] }

Review funnel performance

Tool: get_scenario_analytics

{ "scenario_id": "YOUR-SCENARIO-UUID" }

Fetch store analytics chart data

Tool: get_store_chart — read-only, returns JSON for agents or external clients.

{ "metric": "orders", "range": "days_ago_7", "chart_type": "area" }

Other metrics: visits, conversion, product_creations, stock_movements.

Stock movements for one product

Tool: get_store_chart

{ "metric": "stock_movements", "range": "days_ago_14", "product_title": "Blue Hoodie", "chart_type": "bar" }

Response includes three datasets: movement count, units in, and units out per day. Omit product_id / product_title for store-wide inventory history.

Product creation history

Tool: get_store_chart

{ "metric": "product_creations", "range": "days_ago_21" }

Duplicate an existing scenario

Tool: duplicate_marketing_scenario

{ "scenario_id": "YOUR-SCENARIO-UUID" }

Cursor prompt — cart recovery with A/B test

Using the becomy MCP server: get integrations status, list segments, create a cart_abandoned scenario with min cart value $30, two email variants on an A/B split (winner mode, 7 days, click rate), then show analytics for the draft.

Ask the agent in the theme editor

Open /theme_editor or /admin/appearance and use the Theme assistant panel. The agent updates draft theme files and section settings via MCP theme tools. Click Publish when ready.

Strategy advisor (read-only)

Open /strategy or use the Studio copilot on /admin/studio/home. The agent analyzes products, orders, coupons, marketing scenarios, and can render analytics charts via get_store_chart, but cannot invoke write tools.

Studio copilot chart prompts

Montre-moi un graphique des commandes des 7 derniers jours. Graphique de l'historique de créations de produits. Historique des mouvements de stock sur 14 jours pour le produit "Summer dress".

Create a Father's Day campaign from the copilot

From /admin/studio/home, describe the campaign in natural language. The copilot routes to the campaign agent when your brief is complete. Tools: create_campaign then populate_campaign.

{ "name": "Father's Day 2026", "source_prompt": "Father's Day gift campaign for men 35-55, 15% off, warm tone" }

{ "campaign_id": "YOUR-CAMPAIGN-UUID" }

Open the returned campaign_url in Studio to review the canvas, edit cards, then Validate & schedule to create collection, email scenario, social posts and theme draft.

Update campaign copy via MCP

Tool: update_campaign_card

{ "campaign_id": "YOUR-CAMPAIGN-UUID", "card_kind": "copy", "config": { "instagram": "Last-minute gifts for Dad — 15% off this week." } }

Launch preview (integrations check)

Tool: launch_campaign with confirmed: false

{ "campaign_id": "YOUR-CAMPAIGN-UUID", "confirmed": false }

Returns preview copy, social posts, credit estimate and integration alerts before scheduling.

Read campaign KPIs after launch

Tool: get_campaign_analytics

{ "campaign_id": "YOUR-CAMPAIGN-UUID" }

Returns snapshot (revenue, orders, email sent/opened/clicked, social counts, AI credits spent), ratios (open rate, ROAS on AI credits, conversion rate when collection views exist), and the configured attribution window dates.

In-app AI agents

Becomy ships merchant-facing agents in the admin UI. Each agent uses the same MCP tool classes as external clients (Cursor, Claude Desktop), but runs in-process via RubyLLM with the OpenAI API — no separate MCP HTTP hop per tool call.

Conversations are persisted per store and admin user, with safety tagging on chats/messages and an audit trail in agent_audit_events.

Architecture

MCP tools (app/mcp/) — single source of domain actions
Agent registry (app/agents/agents/agent_registry.rb) — maps agent_kind → agent class + tool allowlist
AgentChatService — orchestration, safety pre-checks, RubyLLM ask loop
AgentSafetyService — input rules, per-kind tool policy, output sanitization

External MCP clients still use POST /mcp with mcp_api_token. In-app agents use admin session auth on the chat endpoints below.

Three MCP surfaces

Surface	Endpoint	Audience
Merchant MCP	`/mcp`	Store admin, Cursor, theme/commerce tools
UCP buyer MCP	`/ucp/mcp`	Platform agents (Google, ChatGPT)
UCP maintenance	`/mcp` (tool subset)	`UcpMaintenanceAgent` in Studio UCP Settings

Unified Studio agent (`studio`)

Becomy AI is a single copilot across Studio and the theme editor. One chat endpoint, intent-based tool subsets, and global conversation history per merchant.

Surface	Chat endpoint	Notes
Studio shell (`/admin/studio/*`)	`POST /admin/studio/agent/chat`	Default copilot dock; global history (`studio\|global`)
Theme editor	`POST /admin/studio/agent/chat`	Same endpoint with `page_key=theme_editor` and design selection metadata
Campaign / automation editors	`POST /admin/studio/agent/chat`	Pass `context_type` + `context_id` for entity-scoped chats

Legacy per-kind agents (commerce, campaign, theme, …) were merged into studio. Old chats remain visible in history with a legacy badge until migrated via rake agent_chats:migrate_to_studio.

Tool allowlists (in-app only)

Each agent kind can only invoke a subset of MCP tools. External MCP clients receive the full tool set.

Theme (`theme`)

All theme tools
list_products, list_collections

Marketing (`marketing`)

All marketing tools (scenarios, segments, analytics, integrations status, duplicate)
list_products, list_coupons, list_orders

Business strategy (`strategy`)

All commerce read tools: list_products, list_collections, list_orders, list_coupons, get_store_chart
list_marketing_scenarios, get_marketing_scenario

Commerce (`commerce`)

All commerce read tools, including get_store_chart
Commerce write tools: get_product, create_product, update_product, archive_product, import_product_from_url

Chat API

All agent endpoints accept JSON (admin session required):

Parameter	Required	Description
`message`	Yes	User prompt (max 4,000 characters)
`chat_id`	No	Continue an existing conversation. Omit to start a new chat.
`confirmed`	No	Set to `true` to approve destructive actions after `requires_confirmation`

Response fields

Field	Description
`chat_id`	Persisted conversation ID — send on the next turn for multi-turn memory
`reply`	Assistant message (HTML stripped for XSS safety)
`tools_used`	Array of MCP tool names invoked this turn
`safety_status`	`clean`, `flagged`, or `blocked`
`safety_tags`	Policy tags applied to the chat (see below)
`requires_confirmation`	`true` when the user must resend with `confirmed: true`
`confirmation_reason`	Human-readable reason when confirmation is required
`reload_preview`	Theme agent only — refresh the theme preview iframe
`reload_graph`	Marketing agent only — reload the flow canvas
`graph`	Marketing agent only — updated scenario graph JSON when `reload_graph` is true
`charts`	Strategy / commerce agents — chart specs for inline rendering when `get_store_chart` was invoked (Studio copilot UI)

Example request

POST /theme_editor/agent/chat Content-Type: application/json { "message": "Make the hero heading blue", "chat_id": 42 }

Confirmation flow

Destructive tools such as activate_marketing_scenario and layout write_theme_file paths return requires_confirmation: true. Resend the same message with confirmed: true to proceed.

Conversation history

GET /agent_chats?agent_kind=theme — recent chats for the signed-in admin (optional filter by kind)
GET /agent_chats/:id — messages for a chat (roles, content, safety tags, tools used)

Browser UIs also persist chat_id in localStorage per agent kind and restore history on load.

Safety model

Built-in policy layer — no external moderation API.

Input — max length, empty-message block, prompt-injection heuristics
Tool policy — per-kind allowlist, draft-context checks, confirmation gates
Output — script-tag stripping before rendering in the UI
Audit — every tool call logged to agent_audit_events with redacted arguments

Safety tags

Tag	Meaning
`injection_suspected`	Blocked prompt patterns
`confirmation_required`	User must resend with `confirmed: true`
`theme_mutation`	Theme file or section settings changed
`scenario_mutation`	Marketing graph changed
`scenario_activation`	Scenario activated
`commerce_mutation`	Product created, updated, archived, or imported via commerce tools
`mutation`	Generic write tool invoked (per-message)
`tool_not_allowed`	Tool blocked by agent-kind allowlist
`draft_required`	Write attempted without draft context (theme/page/scenario)

Rate limits

Agent chat endpoints are limited to 30 requests per admin user per store every 5 minutes. Excess requests return HTTP 429.

Configuration

Variable	Purpose
`OPENAI_API_KEY`	Required for platform LLM calls (or set `openai.api_key` in Rails credentials)
`OPENAI_MODEL`	Default model (e.g. `gpt-5.4-mini`, `gpt-4o-mini`)
`OPENAI_API_BASE_URL`	Optional — default `https://api.openai.com/v1` (use for OpenAI-compatible proxies)
`AGENT_MAX_TOOL_ROUNDS`	Optional — override per-agent tool loop cap (registry defaults: theme 3, marketing 5, strategy 3, commerce 5)

Run bin/rails ruby_llm:load_models after deploy to populate the model registry.

Example prompts by surface

Theme editor

Make the announcement bar background navy and text white on the index template.

Marketing automation

Add a welcome email after customer_signed_up, then a 2-day delay and a coupon grant step.

Strategy advisor

What are my top products by order volume this month? Suggest three campaigns to improve AOV.

Studio copilot — analytics charts

Show me a chart of orders over the last 7 days. Graph the history of product creations this week. Show stock movement history for product "Blue Hoodie".

The agent calls get_store_chart and the Studio copilot renders the graph below the reply. External MCP clients receive the same JSON payload but must render charts themselves.

Commerce copilot

Import this product from URL and show me a chart of new products created this month.

Source code

Agents: app/agents/ (e.g. ThemeEditorAgent, MarketingAutomationAgent)
Prompts: app/prompts/*/instructions.txt.erb
Controllers: studio/agent_controller.rb, agent_chats_controller.rb
Chart services: app/services/store_chart_service.rb, app/mcp/commerce_tools/get_store_chart_tool.rb
Platform: app/services/agent_chat_service.rb, app/services/agent_safety_service.rb
Models: AgentChat, AgentMessage, AgentAuditEvent

Security

Treat mcp_api_token like a password. It grants theme write access and commerce read access.
Becomy stores only a SHA-256 digest of the token. Full plaintext is shown once on signup or rotate (Settings → MCP API token).
Rotate immediately if a token is exposed — use Studio Settings or store.regenerate_mcp_api_token! (returns plaintext once).
Never log or commit the full token. Logs filter *token* parameters.
Always use HTTPS in production. Never send the token over unencrypted connections.
Theme write tools modify the draft theme. Publish from the theme editor to go live.
Marketing write tools target the scenario open in the flow editor (draft). Activation requires explicit user confirmation in the agent UI.
Stdio transport bypasses token auth — restrict to local development machines only.
In-app agents enforce per-kind tool allowlists, draft-context checks, and confirmation for destructive actions. See AI agents.
Tool invocations are recorded in agent_audit_events with redacted arguments for compliance replay.

FAQ

Which theme does the MCP server edit?

The store’s editing theme: the unpublished draft if one exists, otherwise the main (live) theme. Opening the theme editor creates a draft automatically.

How do I create a store via MCP?

Use the apex Platform MCP tool sign_up_store (becomy-platform on http://localhost:5000/mcp in development). Store MCP on a subdomain cannot create stores — it requires an existing host + token.

Why do I get 401 Unauthorized?

Missing or invalid Authorization: Bearer … header, or the request host does not match a store domain_name. Store MCP requests must be sent to your store’s domain. Platform signup on the apex host does not use a Bearer token.

Why do I get 404 Store not found?

The HTTP host must resolve to a store in Becomy (e.g. yourstore.localhost:5000 in development). Check Store.find_by(domain_name: …) matches your subdomain. If you have no store yet, call sign_up_store on the apex first.

Why does the storefront show €0.00 / Sold out after create_product?

Default variants are created archived with 0 stock. Pass price, available, and status: "active" on create_product, or fix later with update_product (that tool syncs products.price and unarchives the variant).

Can I use my own OpenAI key?

Yes. In-app agents (theme, marketing, strategy) call OpenAI via RubyLLM with tool-calling. Set OPENAI_API_KEY on the server (platform-wide), add openai.api_key to Rails credentials, or connect OpenAI per store at /admin/integrations/openai. In-app assistants use the store key when present, otherwise the platform key. External MCP clients (Cursor, Claude Desktop) use POST /mcp with your store’s mcp_api_token and bring their own model provider.

What is the difference between MCP HTTP and in-app agents?

MCP HTTP (/mcp) exposes all tools to external clients authenticated with mcp_api_token. In-app agents use admin session auth, persist conversations, enforce per-kind tool allowlists, and apply safety policies. See AI agents.

Do in-app agents share conversation memory?

Yes, within a chat_id. Each agent kind maintains separate chats per store and admin user. Browser panels restore the last chat_id from localStorage.

How do I customize storefront pages?

Use the theme editor (/theme_editor) and Dawn templates. The legacy GrapesJS page builder was retired; the theme agent edits draft theme files only.

Can MCP send test emails or manage integration API keys?

No. MCP can read integration status via get_store_integrations_status but never returns secrets. Configure providers in the admin UI at /admin/integrations. Test sends are done from the flow editor.

Can MCP render charts in the chat UI?

get_store_chart returns structured JSON (labels, datasets, summary). External MCP clients receive that payload as tool output text. In Becomy Studio, when the strategy or commerce agent calls this tool, the chat API also includes a charts array and the copilot renders graphs inline with Chart.js.

How do campaign tools differ from marketing automation tools?

Marketing automation tools (create_marketing_scenario, etc.) build trigger-based customer journeys. Campaign tools (create_campaign, populate_campaign, launch_campaign) orchestrate a dated marketing canvas: timeline, product selection, AI visuals/video, copy, email scenario, social posts and theme draft. Use campaigns for seasonal promos; use automations for lifecycle flows. See Campaigns guide.

Where is the source code?

Store MCP: app/mcp/becomy_mcp_server.rb · app/controllers/mcp_controller.rb
Platform MCP: app/mcp/platform_mcp_server.rb · app/controllers/platform_mcp_controller.rb · app/mcp/platform_tools/
Tools: app/mcp/theme_tools/, app/mcp/commerce_tools/, app/mcp/marketing_tools/, app/mcp/campaign_tools/
Agents: app/agents/, orchestration in app/services/agent_chat_service.rb

Becomy MCP Server

Overview

Platform MCP (signup)

Server instructions (sent at MCP initialize)

Tool: sign_up_store

Cursor — Platform MCP config

Authentication

Get your token

Rotate a token

HTTP transport

Endpoint

Required headers

Initialize (handshake)

List tools

Call a tool

Stdio transport (local)

Cursor setup

Option A — Remote HTTP (recommended for production)

Option B — Local stdio (development)

Tools reference

Theme tools

Commerce tools (read-only)

get_ai_usage_history periods

Example response (get_ai_usage_history)

get_store_chart metrics

get_store_chart ranges

Example response

Commerce tools (write)

Carnet Becomy (journal) tools

Onboarding tools

Planning calendar tools

Marketing automation tools

Campaign tools

AliExpress dropshipping tools

Examples

Create a store from an agent (Platform MCP)

Create a sellable product (price + stock)

Assign products to a collection

Change the homepage banner heading

Change the announcement bar text (Dawn layout)

Change the primary theme color

Reorder homepage sections

Move announcement bar below the header (Dawn layout)

Add a slideshow slide

Upload an image to the store library

Set a banner image from the asset library

Publish the draft theme (go live)

Remove a section from the index template

Add a new section to the index template

Read the product template

Ask the agent in the theme editor

Check integrations before going live

List segments for a targeted flow

Build a welcome email scenario

Review funnel performance

Fetch store analytics chart data

Stock movements for one product

Product creation history

Duplicate an existing scenario

Cursor prompt — cart recovery with A/B test

Ask the agent in the theme editor

Strategy advisor (read-only)

Studio copilot chart prompts

Create a Father's Day campaign from the copilot

Update campaign copy via MCP

Launch preview (integrations check)

Read campaign KPIs after launch

In-app AI agents

Architecture

Three MCP surfaces

Unified Studio agent (studio)

Tool allowlists (in-app only)

Theme (theme)

Marketing (marketing)

Business strategy (strategy)

Commerce (commerce)

Chat API

Response fields

Example request

Confirmation flow

Tool: `sign_up_store`

`get_ai_usage_history` periods

Example response (`get_ai_usage_history`)

`get_store_chart` metrics

`get_store_chart` ranges

Unified Studio agent (`studio`)

Theme (`theme`)

Marketing (`marketing`)

Business strategy (`strategy`)

Commerce (`commerce`)