# Admin MCP tools

Admin MCP exposes the same **platform tools** Success Agent uses in merchant admin. This page lists those tools by domain. It is not a per-tool API reference: argument schemas live on the server.

Call [`tools/list`](/apis-and-tools/mcp/admin#discover-tools) after you connect. For merchant OAuth tokens that response lists all platform admin tools. Scopes, [permissions](/apis-and-tools/mcp/admin#access-control), and channel type still gate which calls succeed. Descriptions of admin tools include an `Example output:` sample.

OAuth clients receive **platform tools only**. Merchant-configured [MCP Tools](/ai/ai-commerce/mcp-tools) (inbound HTTP or MCP servers) are not attached to OAuth sessions.

Tools that need a sales channel advertise an integer `channel_id` in their schema. Use `list_channels` to discover ids. `get_profile` and `list_channels` do not take a channel. See [Sales channel](/apis-and-tools/mcp/admin#sales-channel).

Successful admin tool results are wrapped in `{ "status": "ok", "response": … }`. `get_profile` and `list_channels` return their objects directly. See [Admin MCP](/apis-and-tools/mcp/admin#responses).

## Account

These tools do not take `channel_id`.

| Tool | Description |
| --- | --- |
| `get_profile` | Return the signed-in user, merchant, and token scopes. |
| `list_channels` | List the merchant's sales channels (`id`, `name`, `type`, `store`). Use an `id` as `channel_id` when a tool schema requires it. Requires `profile`, `sales_channel_read`, or `sales_channel_write`. |

## Products

### Catalog

| Tool | Description |
| --- | --- |
| `get_product` | Get detailed information about a specific product. |
| `search_products` | Search for products using a natural-language query or structured filters. |
| `discover_products` | Find products based on performance metrics or missing content. |
| `get_product_performance_snapshot` | Get views, purchases, revenue, returns, and conversion for one product in a date range. |
| `get_top_and_underperforming_products` | List top or underperforming products by metric within a date range. |
| `create_product` | Create a new product with optional variant options. |
| `update_product_content` | Update product name, summary, and description. |
| `update_product_status` | Update product status (`published` / `unpublished` / `preview`) and admin flag color. |
| `update_product_seo` | Update product URL slug, SEO title, description, and keywords. |
| `update_product_taxonomy` | Update product taxonomy category and attributes, and assign store product groups. |
| `update_product_metadata` | Update manufacturer, delivery time, deliverer, tax class, return policy, notes, and tags. |
| `update_product_media` | Replace product images with a list of media file IDs. |
| `update_product_variant` | Update variant pricing, stock codes, quantity limits, and weight. |
| `add_product_variant` | Add a variant to a product that already has options. |
| `remove_product_variant` | Delete a variant from a product. |

### Inventory

Requires `inventories_read` / `inventories_write` (or `catalog_*`, which maps to the same product permissions). Transfers and some warehouse writes also require the matching plan feature.

| Tool | Description |
| --- | --- |
| `get_product_inventory_status` | Get inventory status for a simple product or variant child. |
| `list_low_or_out_of_stock_products` | List low-stock or out-of-stock products in the channel inventory. |
| `update_product_inventory` | Set, adjust, or update incoming, alarm, or location for a product or variant. |
| `get_inventory_levels` | Get inventory levels for multiple products at once. |
| `set_low_stock_threshold` | Set or clear the low-stock alarm threshold for multiple products. |
| `get_inventory_history` | Get the stock-change history for a product in the channel inventory. |
| `list_storages` | List merchant warehouses (storage locations). |
| `transfer_product_inventory` | Transfer stock of a product or variant between warehouses. |

### Relations

Merchant-configured related, similar, and compatible links. Requires the advanced product details plan feature. This is not purchase-affinity data from `get_product`.

| Tool | Description |
| --- | --- |
| `get_product_relations` | Get related, similar, or compatible product linkages. |
| `update_product_relations` | Set, add, or remove related, similar, or compatible product linkages. |

### Product groups

| Tool | Description |
| --- | --- |
| `get_product_group` | Get a product group by ID. |
| `search_product_groups` | Search product groups with a query or structured filters. |
| `create_product_group` | Create a product group. |
| `update_product_group` | Update a product group. |
| `delete_product_group` | Delete a product group by ID. |

### Manufacturers

| Tool | Description |
| --- | --- |
| `get_manufacturer` | Get a manufacturer by ID. |
| `search_manufacturers` | Search manufacturers. |
| `create_manufacturer` | Create a manufacturer. |
| `update_manufacturer` | Update a manufacturer. |
| `delete_manufacturer` | Delete a manufacturer by ID. |

## Orders

Customer fields on order tools are GDPR-masked.

| Tool | Description |
| --- | --- |
| `search_orders` | Search and filter orders. |
| `get_order` | Get an order including items, payments, shipping, and addresses. |
| `get_order_timeline` | Get the activity timeline (action log) of an order. |
| `update_order_status` | Update order status or payment status. |
| `add_order_note` | Set the internal merchant note on an order (replaces any existing note). |
| `create_refund` | Create a return/refund linked to the original order. |
| `get_order_statistics` | Get aggregated order statistics for the channel. |

## Customers

Personal data in customer tool responses is GDPR-masked (name initial, email domain, last four phone digits, no full address).

| Tool | Description |
| --- | --- |
| `search_customers` | Search customers by name, email, customer number, or tag. |
| `get_customer` | Get a customer by ID. |
| `get_customer_orders` | Get recent orders for a customer. |
| `get_customer_groups` | List customer groups for the channel. |
| `update_customer_tags` | Add or remove tags on a customer. |
| `get_customer_statistics` | Get aggregated customer counts, registrations, subscribers, and top spenders. |
| `get_customer_segments` | Get RFM segment distribution (champions, loyal, regular, at_risk, churned). |

## Media

| Tool | Description |
| --- | --- |
| `search_images` | Search images with a query or structured filters. |
| `get_image` | Get an image by ID. |
| `create_image` | Create an image from a URL or data URL. |
| `update_image` | Update image title, description, tags, and locales. |
| `delete_image` | Delete an image by ID. |
| `validate_image_url` | Validate an image URL and return width, height, size, and format. |
| `search_videos` | Search videos with a query or structured filters. |
| `create_video` | Add a video from a YouTube, Vimeo, or direct URL. |
| `update_video` | Update video title, description, tags, and locales. |
| `delete_video` | Delete a video by ID. |
| `validate_video_url` | Validate a video URL and return metadata. |

## Marketing and discounts

| Tool | Description |
| --- | --- |
| `create_product_discount` | Create a product discount campaign (optionally as a coupon). |
| `create_shipping_discount` | Create a shipping discount campaign (optionally as a coupon). |
| `create_buy_x_get_y_discount` | Create a buy X get Y discount campaign (optionally as a coupon). |
| `create_volume_discount` | Create a volume discount with amount-based steps. |
| `create_loyalty_discount` | Create a loyalty discount based on lifetime purchase amount. |
| `set_discount_status` | Activate or deactivate a discount campaign. |
| `search_discounts` | Search and list discounts and campaigns. |
| `get_discount` | Get a discount including rules, conditions, and coupon info. |
| `get_discount_usage` | Get redemption statistics for a coupon-based discount. |

## Marketing messages

Webstore and POS channels. These edit marketing emails, not storefront theme files. Listing, reading, the email designer schema, and preview require `marketing_read`. `create_marketing_message` and content or designer edits require `marketing_write`. None of these tools publish or send.

| Tool | Description |
| --- | --- |
| `list_marketing_messages` | List marketing email messages on the channel (no HTML or MJML). Filter by type, status, or name/subject search. |
| `get_marketing_message` | Get one marketing email, including editor, send time, draft subject, and draft content. |
| `create_marketing_message` | Create a draft marketing email (`newsletter`, `announcement`, `transactional`, or `automatic`). |
| `update_marketing_message` | Update the message name and/or `send_at`. |
| `update_marketing_message_content` | Update draft subject and MJML/Liquid for `html` editor messages. |
| `preview_marketing_message` | Render a draft email preview. HTML is size-capped. |
| `list_email_designer_schema` | List email designer section and block types for the channel. |
| `add_email_section` | Add a designer section (`column`, `two-columns`, `hero`, `header`, `footer`, `cart`, …). |
| `update_email_section` | Update settings on a designer section. |
| `remove_email_section` | Remove a designer section. |
| `move_email_section` | Move a designer section to a new position. |
| `add_email_block` | Add a designer block (`text`, `image`, `button`, `divider`, `spacer`, `logo`, `product`, …) to a section. |
| `update_email_block` | Update settings on a designer block. |
| `remove_email_block` | Remove a designer block. |
| `move_email_block` | Move a designer block to a new position. |

## Social

Webstore and POS channels. Requires a marketing view, create, or edit permission (`marketing_read` is enough to list them). Ideas stay in Finqu until a draft is published.

| Tool | Description |
| --- | --- |
| `list_social_accounts` | List social accounts on the channel and whether each account is ready to post. |
| `list_social_posts` | List social posts in a date range. |
| `get_social_post` | Get a social post, including per-account publish status, permalinks, and errors. |
| `create_social_post_idea` | Save a calendar idea. Ideas are not sent to social platforms. |
| `create_social_post_draft` | Create a draft with caption, target accounts, and optional media library files. |
| `update_social_post` | Update an idea, draft, or scheduled post. Requires the `version` from the last read. |
| `publish_social_post` | Publish a draft now, or schedule it with a future `scheduled_at`. |
| `retry_social_post` | Retry a failed post on the accounts that failed. |
| `delete_social_post` | Delete a post. Requires `confirm: true`. Published posts are removed from Finqu only. |

## Calendar

Requires `sales_channel_read` (channel view) and a `channel_id`.

| Tool | Description |
| --- | --- |
| `list_calendar_events` | List desktop calendar events for `marketing`, `operations`, `customers`, or `work-hub`. `from` / `to` are `YYYY-MM` or `YYYY-MM-DD` (default: the current month). |

## Content

### Pages and articles

| Tool | Description |
| --- | --- |
| `search_pages` | Search pages by name, list pages, or get a page by ID. |
| `create_or_update_page` | Create or update a page with content and SEO metadata. |
| `search_articles` | Search blog articles by title, list articles, or get an article by ID. |
| `create_or_update_article` | Create or update an article with content and metadata. |

### SEO analytics

These tools require `analytics_read` (analytics view permission), not content-editing scopes.

| Tool | Description |
| --- | --- |
| `get_keyword_ranking_history` | Track historical ranking positions for keywords you provide. |
| `get_keyword_analytics` | Discover keywords with rankings, opportunities, and competitive analysis. |
| `get_content_performance` | Analyze performance metrics for website content. |
| `get_backlink_profile` | Analyze website backlink profile and quality metrics. |

### Navigation

Webstore channels only. Requires `sales_channel_read` / `sales_channel_write`.

| Tool | Description |
| --- | --- |
| `find_linkable_resources` | Search products, categories, pages, articles, and manufacturers for navigation links. |
| `list_navigation_menus` | List navigation menus without their items. |
| `get_navigation_menu` | Get a navigation menu structure and items by token. |
| `add_navigation_item` | Add an item to a navigation menu. |
| `update_navigation_item` | Update a navigation menu item. |
| `remove_navigation_item` | Remove a navigation menu item and all its children. |
| `update_navigation_item_description` | Update or add a language-specific description for a navigation item. |

## Theme

Theme tools require a **webstore** channel. Pass that channel as `channel_id`. They use the current or public release and the `frontpage` template.

### Settings and files

| Tool | Description |
| --- | --- |
| `get_theme_context` | Get a compact theme digest: colors, fonts, settings summary, and file naming conventions. |
| `get_current_template` | Get the current template ID, resource type, and resource ID. |
| `get_template_snapshot` | Get the full section structure and configuration of a template. |
| `list_templates` | List editable templates in the current theme. |
| `update_theme_settings` | Update theme-wide settings such as colors, typography, and layout options. |
| `search_theme_settings` | Search theme settings by keyword, category, or functionality. |
| `get_related_theme_settings` | Get settings related to a functionality or design element. |
| `get_theme_colors` | List color settings with labels and current hex values. |
| `update_theme_colors` | Update one or more theme color settings. |
| `list_available_themes` | List themes available to install. |
| `list_installed_themes` | List installed themes and their releases. |
| `install_theme` | Install or update a theme. |
| `activate_theme` | Activate a theme release on the storefront. |
| `list_theme_files` | List files and directories in a theme directory. |
| `fetch_theme_file` | Read one theme file (`outline`, `schema`, or `full` mode). |
| `fetch_theme_files` | Read multiple theme files in one call (max 10). |
| `search_theme_files` | Search theme files by filename, glob, or extension. |
| `grep_theme_files` | Search theme file contents with optional context lines. |
| `save_theme_file` | Create or update a theme file. |
| `patch_theme_file` | Replace an exact substring in a theme file. |
| `delete_theme_file` | Delete a theme file. |
| `rename_theme_file` | Rename or move a theme file within the theme. |
| `copy_theme_file` | Duplicate a theme file to a new path. |

### Sections and blocks

| Tool | Description |
| --- | --- |
| `get_theme_sections` | List section types (handles) available in the current theme. |
| `get_theme_section` | Get the configuration schema and settings for a section type. |
| `list_template_sections` | List static and dynamic sections in a template. |
| `update_section_settings` | Update settings of an existing section instance. |
| `add_dynamic_section` | Add a section instance to a template at a given position. |
| `duplicate_dynamic_section` | Duplicate a section instance with its settings. |
| `remove_dynamic_section` | Permanently remove a section instance. |
| `move_dynamic_section` | Move a section within a template layout. |
| `get_section_translations` | List language translations for a section instance. |
| `add_section_translation` | Add a language translation copied from an existing language. |
| `remove_section_translation` | Remove a language translation from a section. |
| `get_theme_blocks` | List block types available in the current theme. |
| `get_theme_block` | Get the configuration schema for a block type. |
| `list_section_blocks` | List layout block instances in a section. |
| `add_section_block` | Add a block instance to a section or a layout block container. |
| `update_block_settings` | Update settings on an existing block instance. |
| `remove_section_block` | Remove a block instance (and nested children that reference it). |
| `move_section_block` | Reorder a block within its container. |

### Section groups

| Tool | Description |
| --- | --- |
| `list_section_groups` | List section groups (for example header-group, footer-group) and their sections. |
| `add_section_to_group` | Add a section instance to a section group. |
| `remove_section_from_group` | Remove a section instance from a section group. |
| `move_section_in_group` | Move a section within a section group. |
| `update_section_group_settings` | Update the settings of a section within a section group. |

## Store setup

### Taxes

| Tool | Description |
| --- | --- |
| `get_tax` | Get a tax by ID, or `"default"` for the default tax. |
| `search_taxes` | List all taxes. |
| `create_tax` | Create a tax class with tax rates. |
| `update_tax` | Update a tax by ID. |
| `delete_tax` | Delete a tax by ID. |
| `set_default_tax` | Set the default tax by ID. |

### Deliverers

| Tool | Description |
| --- | --- |
| `get_deliverer` | Get a deliverer by ID, or `"default"` for the default deliverer. |
| `search_deliverers` | Search deliverers. |
| `create_deliverer` | Create a deliverer. |
| `update_deliverer` | Update a deliverer. |
| `delete_deliverer` | Delete a deliverer by ID. |
| `set_default_deliverer` | Set the default deliverer by ID. |

### Reviews

| Tool | Description |
| --- | --- |
| `search_reviews` | Search product reviews (filter by status, product, rating, or date range). |
| `get_review` | Get a review including text, rating, and product info. |
| `update_review_status` | Accept or deny a product review. |

### Policies

Handles: `terms-conditions`, `shipping`, `privacy`, `return`.

| Tool | Description |
| --- | --- |
| `get_policy` | Get a store policy by handle. |
| `update_policy` | Update a store policy. |

### Analytics

| Tool | Description |
| --- | --- |
| `get_comprehensive_business_analytics_overview` | Get an analytics overview: revenue, conversions, customers, marketing, geography, and forecasts. |
| `get_predictive_forecasts` | Generate predictive forecasts for key business metrics. |
| `update_marketing_spend` | Create or update marketing spend data for campaigns, channels, or periods. |
| `get_anomaly_detection_results` | Detect anomalies and outliers in business metrics. |

### Channel and store

Channel address and organization category require `sales_channel_write`. Merchant and billing address require `settings_write`.

| Tool | Description |
| --- | --- |
| `list_organization_categories` | List organization categories that can be assigned to a store channel. |
| `set_channel_organization_category` | Set the organization category for the current store channel. |
| `update_channel_address` | Update the public-facing store channel address. |
| `update_merchant_address` | Update the primary merchant (owner) address. |
| `update_billing_address` | Update the merchant billing address. |