docs: add mcp tool copilot approval flow

[D.Francos (dfrancos-hub)]

Summary

Adds a guide to make MCP tools recognized by Copilot and how to create approval flows.

Checklist

• I reviewed affected links, code samples, and cross-references, including PageRef references where relevant.
• I added or updated redirects in .gitbook.yaml if pages were moved, renamed, or deleted.
• I updated .wordlist.txt (and sorted it) if spellcheck flags new legitimate terms.
• Any required dependent changes in downstream modules have already been merged and published.
• This pull request is ready for review.

[shopware-dev-docs-connector]

Developer Docs healthcheck

Status: Completed with success.
Repository: shopware/docs
Commit: 7f9ed57
Preview: https://developer-documentation-17tlnab3q-shopware-frontends.vercel.app
Workflow run: #5335

[Copilot]

🟡 Changes recommended

The critical dryRun issue and several moderate documentation inaccuracies must be corrected.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a Shopware Copilot MCP tool approval-flow guide.

Changes:

• Documents discovery, grouping, and approval behavior.
• Adds plugin and app implementation guidance.
• Includes testing steps, limitations, and publishing guidance.

Review findings include one critical dryRun handling issue, multiple moderate plugin/app accuracy issues, and minor link, wording, and discoverability fixes.

File summaries

File	Description
products/tools/mcp-server/copilot-tool-approval.md	New Copilot MCP approval-flow guide

Review details

Suppressed comments (5)

products/tools/mcp-server/copilot-tool-approval.md:262

• This relative link has the same path problem as the prerequisite link above: it resolves one directory too high and will not reach products/tools/mcp-server/index.md. Use ./index.md.

Now that your tools follow the approval contract, see [MCP Support in Shopware](../index.md) for the full list of tool, resource, and prompt extension points the MCP server offers.

products/tools/mcp-server/copilot-tool-approval.md:8

• The MCP section's intro.md explicitly lists every page in its “In this section” table, but this new guide is absent, so readers following the section overview cannot discover it. Add a row for this page to that table (and link it from the Copilot entry if desired).

# Making Your MCP Tools Work With Shopware Copilot

products/tools/mcp-server/copilot-tool-approval.md:220

• This privilege guidance applies plugin-only APIs to app tools as well. requirePrivilege() and McpToolRequires are PHP plugin mechanisms; app tools declare <required-privileges> in mcp.xml, and external webhooks must enforce access themselves. Split the instructions so app authors are not told to use unavailable APIs.

* **Privileges are the merchant's** - Copilot acts with the permissions of the merchant who is chatting. Check the privilege your change needs with `requirePrivilege()` and declare it with `McpToolRequires` so that shop administrators can configure roles.

products/tools/mcp-server/copilot-tool-approval.md:48

• McpToolGroup applies to in-process plugin and bundle tools, but app tools cannot declare that PHP attribute; Shopware automatically groups all tools from an active app into a toolset named after the app's technical name (guides/plugins/apps/mcp-server.md:55-57). Because this guide targets apps as well as plugins, the current wording makes app authors look for a group setting that does not exist and omits the actual grouping rule.

* **Group name** - Tools that share a `McpToolGroup` become one toolset. Use a short, stable, product-specific name such as `b2b-quotes` rather than a generic one like `tools`.

products/tools/mcp-server/copilot-tool-approval.md:145

• The class is declared in Vendor\MyExtension\Mcp\Tool, so the unqualified PromotionService type resolves to Vendor\MyExtension\Mcp\Tool\PromotionService; no such service is imported or defined in this example. Unless the domain service is intentionally in that namespace, the advertised complete tool will not compile. Import the actual service class and use the same class in the DI registration.

    public function __construct(
        private readonly PromotionService $promotions,
        private readonly McpContextProvider $contextProvider,

• Files reviewed: 1/1 changed files
• Comments generated: 8
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.