docs: add MCP server documentation by BrocksiNet · Pull Request #2264 · shopware/docs

Björn Meyer (BrocksiNet) · 2026-04-23T14:36:46Z

Summary

Adds complete documentation for Shopware's native MCP server introduced in 6.7:

guides/development/tooling/mcp-server/ — 8 pages covering concepts, getting started, configuration, best practices, examples, troubleshooting, tools reference, and Shopware extensions (Copilot, SwagMcpMerchantAssistant, SwagMcpDevTools, ai-coding-tools)
guides/plugins/plugins/mcp-server.md — how-to for extending via plugin
guides/plugins/apps/mcp-server.md — how-to for extending via app (webhook)
4 Admin UI screenshots for tool allowlist and ACL privilege flows
Navigation entries in tooling, plugins, apps, and extensions indexes

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.

Notes

Adds complete documentation for Shopware's native MCP server introduced in 6.7: - guides/development/tooling/mcp-server/ — 8 pages covering concepts, getting started, configuration, best practices, examples, troubleshooting, tools reference, and Shopware extensions (Copilot, SwagMcpMerchantAssistant, SwagMcpDevTools, ai-coding-tools) - guides/plugins/plugins/mcp-server.md — how-to for extending via plugin - guides/plugins/apps/mcp-server.md — how-to for extending via app (webhook) - 4 Admin UI screenshots for tool allowlist and ACL privilege flows - Navigation entries in tooling, plugins, apps, and extensions indexes

references - Fix McpContextProvider namespace (Context\ sub-namespace) and requirePrivilege return value pattern in plugin sample code - Fix shopware-media-upload has no dryRun, theme-config action/config defaults, debug:mcp column list, tool count claim - Add extending.md: side-by-side quick reference for tools/prompts/resources across app, plugin, and bundle - Add webhook handler examples for prompts and resources in apps/mcp-server.md - Link SwagMcpAdminUsers and McpHelloWorld example repos in plugin and app docs - Expand MCP acronym on first use in mcp-concepts.md, fix lowercase mcp in headings to use backticks - Fix duplicate heading in shopware-extensions.md

- Document required-privileges in app mcp.xml (informational only; apps must enforce ACL themselves) - Add array/object to supported input schema property types - Add internal URL mode (url="/...") for routing to app scripts - Document integration.mcp_tool_allowlist semantics (null/array/empty) - Replace stale mcp.yaml snippet with mcp.php note; clarify the bundle loads automatically when MCP_SERVER feature flag is active - Add --integration flag to debug:mcp; remove non-existent --all flag - Add Symfony bundle stub guide

reference - Add three new subsections to best-practices.md: writing descriptions for agent routing, the DI container cache requirement after description changes, and using the system prompt as the disambiguation override layer - Fix shopware-theme-config salesChannelId row in tools-reference.md to reflect that it is optional in the schema and validated at runtime

- Rename "Edit MCP Tools" → "Edit MCP Allowlist" across all docs - Update integration.mcp_tool_allowlist semantics to mcp_allowlist (JSON object with tools/resources/prompts keys, scoped to integration credentials only — admin user bearer tokens bypass the allowlist) - Document scope in configuration.md and add a row to the troubleshooting quick reference explaining why bearer tokens see all capabilities - Replace four allowlist UI screenshots with new versions reflecting vendor groupings, expandable tool descriptions, and the per-type toggles (tools/resources/prompts) - Add a "Limit tool count" illustration to best-practices.md showing the inline privilege-gap warnings when everything is enabled - Clarify in configuration.md that the bundle config loads automatically only when the MCP_SERVER feature flag is active - Replace "eval" with "evaluation" in best-practices.md for clarity

- Drop Feature::has('MCP_SERVER') gate from bundle build() examples; core mcp.php loads services unconditionally and only the controller checks the flag - Add title attribute to McpTool/McpPrompt examples and document its purpose - Clarify configuration.md: symfony/mcp-bundle's mcp.php is loaded unconditionally; the flag gates /api/_mcp only - Point bundle extension docs to the new bundle.md#optional-bundles pattern (gate in bundles.php, not build()) - Fix compiler pass name: McpToolCompilerPass → McpToolDiscoveryCompilerPass

Copilot

Pull request overview

Adds a new documentation section for Shopware’s native MCP server (6.7+) and extension guides for contributing MCP capabilities via plugins and apps, plus navigation and spellcheck updates to surface the new content across the docs.

Changes:

Add a new guides/development/tooling/mcp-server/ documentation set (concepts, setup, configuration, best practices, examples, troubleshooting, tools reference, extensions).
Add “extend via plugin” and “extend via app” how-tos, and link them from the plugin/app guide indexes.
Update navigation entries and expand .wordlist.txt for MCP-related terminology.

Reviewed changes

Copilot reviewed 19 out of 24 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
guides/plugins/plugins/mcp-server.md	New guide for extending MCP via Shopware plugin/Symfony bundle (tools/prompts/resources).
guides/plugins/plugins/index.md	Adds MCP extension entry to plugin topic index table.
guides/plugins/plugins/bundle.md	Adds “Optional bundles” guidance (InstalledVersions/Feature guards).
guides/plugins/apps/mcp-server.md	New guide for extending MCP via apps (mcp.xml + webhook protocol).
guides/plugins/apps/index.md	Adds link to the new MCP app extension guide.
guides/development/tooling/using-watchers.md	Renames nav title to “Hot Module Replacement”.
guides/development/tooling/mcp-server/index.md	New MCP server landing page (capabilities, architecture, section index).
guides/development/tooling/mcp-server/mcp-concepts.md	New concepts page explaining tools/resources/prompts.
guides/development/tooling/mcp-server/getting-started.md	New setup guide for enabling MCP and configuring clients.
guides/development/tooling/mcp-server/configuration.md	New configuration guide (feature flag, allowlists, session store, CLI).
guides/development/tooling/mcp-server/best-practices.md	New best-practices guide for MCP tool/prompt/resource design.
guides/development/tooling/mcp-server/examples.md	New end-to-end workflow examples using core tools/resources.
guides/development/tooling/mcp-server/extending.md	New side-by-side extension reference (app vs plugin vs bundle).
guides/development/tooling/mcp-server/troubleshooting.md	New troubleshooting quick reference and common issues.
guides/development/tooling/mcp-server/tools-reference.md	New reference for built-in tools/resources/prompt and parameters.
guides/development/tooling/mcp-server/shopware-extensions.md	New overview of MCP-related Shopware extensions/projects.
guides/development/tooling/index.md	Adds MCP Server entry to tooling overview.
guides/development/extensions/index.md	Adds MCP extensibility section linking to plugin/app guides.
.wordlist.txt	Adds MCP-related terms for spellcheck.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- Fix broken relative links (../../plugins → ../../../plugins) in index and mcp-concepts - Align bundle prompt/resource tabs with feature-flag guidance (gates HTTP endpoint, not DI) - Harden Node.js HMAC example: guard missing signature and mismatched lengths - Clarify admin user vs --admin integration in configuration and troubleshooting tables - Fix "Hot Module Reloading" → "Hot Module Replacement" for consistency in using-watchers - Add products/tools/ index and lightweight MCP Server entry point linking to full docs

- verifySignature: guard missing signature, use digest() directly and Buffer.from(signature, 'hex') so timingSafeEqual compares raw HMAC bytes instead of UTF-8-encoded hex strings - remove unused Archlinux entry from .wordlist.txt

Copilot

Pull request overview

Copilot reviewed 21 out of 26 changed files in this pull request and generated 9 comments.

Copilot

Pull request overview

Copilot reviewed 23 out of 28 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 23 out of 28 changed files in this pull request and generated 2 comments.

Micha Hobert (Isengo1989)

Thanks for the PR Björn Meyer (@BrocksiNet) 👍

Changed the tooling JSONs as discussed

Paul Riga (RigaPaul)

Left a few minor comments, but overall it's good

Micha Hobert (Isengo1989) · 2026-06-01T13:46:36Z

Bojan Rajh (@bojanrajh) what is the new workflow to add MCP to tooling in the top menu?

Bojan Rajh (bojanrajh) · 2026-06-01T13:54:03Z

Micha Hobert (@Isengo1989) Should be as simple as fixing the navigation.ts (once this PR is merged), but it would be nice to move the contents from guides/development/tooling/mcp-server to products/tools/mcp-server for a dedicated sidebar.

Björn Meyer (BrocksiNet) mentioned this pull request Apr 23, 2026

Publish MCP v1 documentation on developer.shopware.com/docs shopware/shopware#16266

Open

Björn Meyer (BrocksiNet) added 13 commits April 24, 2026 08:27

fix: markdown and spellchecker

f8eb353

docs(mcp): add hint feature flag

8b18a04

fix(docs): update wordlist

4ad5e9d

feat: update docs to changes

d1e442b

feat: docs about user-id for apps, user allowlist in bearer token case

76a14c0

fix: add text to codeblock

f0c2df7

Merge branch 'main' into feat/mcp-server-documentation

efc858f

Merge branch 'main' into feat/mcp-server-documentation

fdcac02

Björn Meyer (BrocksiNet) marked this pull request as ready for review May 20, 2026 09:04

Copilot AI review requested due to automatic review settings May 20, 2026 09:04

Copilot started reviewing on behalf of Björn Meyer (BrocksiNet) May 20, 2026 09:04 View session

Copilot AI reviewed May 20, 2026

View reviewed changes

Micha Hobert (Isengo1989) requested review from Micha Hobert (Isengo1989), somethings (lasomethingsomething) and Su (sushmangupta) May 20, 2026 14:06

Micha Hobert (Isengo1989) added the Undocumented Feature Feature which is not documented yet and is considered for documentation label May 20, 2026

somethings (lasomethingsomething) requested review from Paul Riga (RigaPaul) and removed request for somethings (lasomethingsomething) May 20, 2026 14:21

Bojan Rajh (bojanrajh) mentioned this pull request May 20, 2026

feat: create products/tools space, move Shopware CLI #2297

Merged

5 tasks

Björn Meyer (BrocksiNet) added 2 commits May 21, 2026 08:14

Merge branch 'main' into feat/mcp-server-documentation

9f2bad6

Björn Meyer (BrocksiNet) requested a review from Copilot May 21, 2026 06:16

Copilot started reviewing on behalf of Björn Meyer (BrocksiNet) May 21, 2026 06:16 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

fix: links and images

27f611a

Björn Meyer (BrocksiNet) requested a review from Copilot May 21, 2026 06:56

Copilot started reviewing on behalf of Björn Meyer (BrocksiNet) May 21, 2026 06:56 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

Comment thread guides/plugins/apps/mcp-server.md Outdated

Comment thread guides/plugins/apps/mcp-server.md

Comment thread guides/plugins/plugins/mcp-server.md Outdated

fix: plugin name, URI and result body text

4c98108

Björn Meyer (BrocksiNet) requested a review from Copilot May 21, 2026 07:06

Copilot started reviewing on behalf of Björn Meyer (BrocksiNet) May 21, 2026 07:06 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

Comment thread guides/plugins/apps/mcp-server.md Outdated

Comment thread guides/plugins/apps/mcp-server.md Outdated

Björn Meyer (BrocksiNet) and others added 4 commits May 21, 2026 09:48

fix: clarify app secret, link to raw

4b2e452

Merge branch 'main' into feat/mcp-server-documentation

06e6c6d

fix/tables-and-small-grammar

4fb5b15

changed/json-code-examples

cc65e1c

Micha Hobert (Isengo1989) approved these changes May 21, 2026

View reviewed changes

Björn Meyer (BrocksiNet) added 2 commits May 22, 2026 11:05

fix: update docs to current code

a73c168

fix: wording

c1ffb49

Micha Hobert (Isengo1989) self-assigned this May 26, 2026

fix grammar

3d25297

Su (sushmangupta) approved these changes May 26, 2026

View reviewed changes

Su (sushmangupta) and others added 2 commits May 28, 2026 15:43

Fix markdown and spelling

94d105e

Merge branch 'main' into feat/mcp-server-documentation

52788f8

Paul Riga (RigaPaul) reviewed Jun 1, 2026

View reviewed changes

Comment thread guides/development/tooling/mcp-server/index.md

Paul Riga (RigaPaul) reviewed Jun 1, 2026

View reviewed changes

Comment thread guides/plugins/plugins/mcp-server.md

Paul Riga (RigaPaul) reviewed Jun 1, 2026

View reviewed changes

Comment thread guides/plugins/plugins/mcp-server.md Outdated

Paul Riga (RigaPaul) approved these changes Jun 1, 2026

View reviewed changes

Micha Hobert (Isengo1989) added 2 commits June 1, 2026 15:41

fix/comments

2a03824

Merge branch 'main' into feat/mcp-server-documentation

d3c0b13

Conversation

Björn Meyer (BrocksiNet) commented Apr 23, 2026 • edited by Isengo1989 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related links

Checklist

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Micha Hobert (Isengo1989) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Paul Riga (RigaPaul) left a comment

Choose a reason for hiding this comment

Uh oh!

Micha Hobert (Isengo1989) commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Bojan Rajh (bojanrajh) commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Björn Meyer (BrocksiNet) commented Apr 23, 2026 •

edited by Isengo1989

Loading

Micha Hobert (Isengo1989) commented Jun 1, 2026 •

edited

Loading