Prompts

Prompts are reusable message templates that AI clients can discover and invoke. When a user selects a prompt, the MCP server returns a pre-built message that the AI uses as context for the conversation. Prompts are part of the MCP specification and appear as slash commands in compatible AI clients.

Most AI clients use the format /<mcp_server_name>:<prompt_code> for MCP-served prompts. For example, if your MCP server is named magento, the bestsellers prompt would be invoked as /magento:show_bestsellers. To see all prompts provided by your MCP server, type / followed by the server name (e.g. /magento) — the autocomplete will list all available prompts from that server. You can also type part of the prompt code (e.g. /show) and the client will match it automatically.

The Prompts grid is available at System → AI Agent Connector → Prompts.

Pre-defined vs custom prompts

The extension ships with several pre-defined prompts for common Magento tasks:

Prompt	Description	Required tools
check_store_config	Verify store configuration — URLs, currencies, contact info	Store Info, Database Reader
show_bestsellers	Top-selling products for a given period	Database Reader
sales_overview	Revenue, order count, and average order value	Database Reader
low_stock_alert	Products below their configured low stock threshold	Database Reader
order_fulfillment_status	Orders stuck in processing or pending	Database Reader
disable_stale_products	Find and disable products with no stock and no recent sales	Database Reader, REST API
fix_missing_url_rewrites	Find products without URL rewrites and regenerate them	Database Reader, REST API

Pre-defined prompts are read-only. You cannot edit their content, arguments, or dependencies. You can only toggle them active/inactive. To customize a pre-defined prompt, use the Duplicate action — this creates an editable copy.

Custom prompts are fully editable. You can create them from the admin panel or through the REST API.

Pre-defined prompts are updated automatically when you run bin/magento setup:upgrade. If a pre-defined prompt is removed from a future version, it will be deleted from the database during upgrade.

Prompt form

General

• Title — Display name shown in the admin grid.
• Code — Unique identifier. This is the name exposed to MCP clients. Must be unique across all prompts.
• Active — Toggle to enable or disable the prompt. Disabled prompts are not returned in prompts/list.

Content

• Description — Short summary shown in the MCP client's prompt picker. Helps users understand what the prompt does before invoking it.
• Content — The prompt template. This is the text sent to the AI when the prompt is invoked. Use {{argument_name}} placeholders for arguments. The content should include specific instructions — table names, column names, query patterns — so the AI knows exactly how to perform the task.

Arguments

Arguments are optional parameters that the user can provide when invoking the prompt. Each argument has:

• Name — The placeholder name used in the content template (e.g. limit for {{limit}}).
• Description — Explains the argument's purpose and accepted values. This is visible to both the user and the AI client.
• Required — Whether the argument must be provided. Required arguments must be listed before optional ones — the system automatically reorders them on save.

When a prompt is invoked, the server substitutes {{argument_name}} placeholders with the provided values. Unfilled optional placeholders are removed from the content.

Client behavior notes

Some MCP clients split user input by spaces and map tokens positionally to declared arguments. Multi-word values may be truncated to a single word. Use single-word argument values (numbers, codes) for best compatibility. If the prompt declares arguments, the client may require the user to provide at least one value before invoking the prompt, even when all arguments are optional.

Dependencies

• Required tools — Select which MCP tools the prompt depends on. If the user does not have access to any of the listed tools, the prompt is hidden from prompts/list. This prevents users from seeing prompts they cannot execute.
• Source module — Shows which Magento module provides this prompt. Used for filtering — if the source module is disabled, the prompt is hidden. This field is set automatically for pre-defined prompts.

Prompt validation

The extension validates prompts automatically:

• Unused arguments — An argument is declared but its {{placeholder}} is not found in the content.
• Undeclared placeholders — A {{placeholder}} appears in the content but no matching argument is declared.

Validation results appear in the Validation column of the Prompts grid ("OK" or "Needs attention") and as warning messages on the prompt edit page.

Tool-dependent filtering

Prompts can declare required tools in the Required tools field. When the MCP server builds the prompts/list response, it checks whether the authenticated user has access to all listed tools. If any tool is inaccessible (due to role permissions or OAuth scopes), the prompt is excluded from the list.

This ensures users only see prompts they can actually use.

Module-aware filtering

Each pre-defined prompt records which Magento module provides it. If that module is disabled, the prompt is automatically hidden from prompts/list — even if it still exists in the database.

REST API

Prompts can be managed through the Magento REST API. All endpoints require admin authentication and the Mirasvit_McpPrompt::prompts ACL resource (or prompts_edit / prompts_delete for write operations).

Method	Endpoint	Description	ACL
GET	/V1/mcp/prompts	List all prompts	prompts
GET	/V1/mcp/prompts/:id	Get prompt by ID	prompts
POST	/V1/mcp/prompts	Create a custom prompt	prompts_edit
PUT	/V1/mcp/prompts/:id	Update a prompt	prompts_edit
DELETE	/V1/mcp/prompts/:id	Delete a custom prompt	prompts_delete

Create request body:

{
    "title": "My Prompt",
    "content": "Show top {{limit}} products",
    "description": "Custom report",
    "arguments": "[{\"name\":\"limit\",\"description\":\"Number of products\",\"required\":false}]",
    "requiredTools": "builtin_system_dbreader",
    "isActive": true
}

The code is auto-generated from the title with a unique suffix if needed.

Update for pre-defined prompts only allows changing isActive. All other fields are ignored.

Delete is blocked for pre-defined prompts.

Adding prompts from custom modules

Any Magento module can ship pre-defined prompts by placing a prompts.yaml file at etc/mcp/prompts.yaml. The extension discovers these files from all installed modules during setup:upgrade.

Example etc/mcp/prompts.yaml:

- code: my_custom_report
  title: Custom report
  description: Generate a custom sales report.
  content: |
    Generate a sales report.
    Query the sales_order table for orders in the last {{months}} months.
    Include order count, total revenue, and average order value.
  arguments:
    - name: months
      description: "Number of months (default 3)"
      required: false
  required_tools: builtin_system_dbreader
  is_active: true

The module field is set automatically from the module name — do not include it in the YAML.

When a module is uninstalled and setup:upgrade is run, any prompts from that module are automatically removed from the database.