Repository navigation
docs: update MCP server docs for 6.7.17 - #2646
Draft
Björn Meyer (BrocksiNet) wants to merge 15 commits into
Draft
Björn Meyer (BrocksiNet) wants to merge 15 commits into
Björn Meyer (BrocksiNet) wants to merge 15 commits into
Conversation
Cover symfony/mcp-bundle 0.13, connect-time toolset selection, 401 on OAuth errors, the fail-closed MCP allowlist, and entity tool parameter contracts.
Checked against a trunk lane on mcp-bundle 0.13 / mcp/sdk 0.8.1: the per-server `cache` recipe puts both stores on Psr16SessionStore with separate prefixes, sessions survive losing the local cache dir, and a removed Redis key is refused with "Session not found or has expired." A recipe that is not picked up leaves the file store running silently, so add the debug:container check that tells the two apart. The active session registry that app-driven tools/list_changed broadcasts fan out to lives in cache.system, which is per server. Document pointing both registries at the shared pool, and the lock store they depend on.
The registry is written without a TTL and falls back to the pool's default_lifetime. It is rewritten on every MCP request, so it outlives its sessions unless default_lifetime is shorter than session.ttl.
The 6.7.16.0 changes (unset allowlist grants nothing, entity tool parameter descriptions and criteria errors) move to their own PR, because 6.7.16.0 is not released yet.
An unset MCP allowlist grants nothing for integrations and non-admin users (shopware/shopware#20600), and the entity tools describe their parameters in inputSchema and name rejected criteria elements (shopware/shopware#20013).
Both endpoints lose their sessions on the update, the Store API services have direct replacements, the Store API session text no longer claims a shared store, the tool example documents its parameters, and a missing bearer token is told apart from an expired one.
# Conflicts: # products/tools/mcp-server/troubleshooting.md
# Conflicts: # guides/plugins/plugins/mcp-server.md # products/tools/mcp-server/configuration.md # products/tools/mcp-server/index.md # products/tools/mcp-server/intro.md # products/tools/mcp-server/tools-reference.md # products/tools/mcp-server/troubleshooting.md
Cover the MCP Iteration 3 changes merged into shopware/shopware trunk: structuredContent, isError and error codes in tool results, signed resource_link pointers and the tool result cache TTL, the reserved discovery group, list change notifications without a session registry, sliding window rate limits, symfony/mcp-bundle 0.14.1, and deleting many-to-many links through the mapping entity. Correct the allowlist upgrade steps, parameter descriptions with #[Schema], the histogram aggregation type, and the MCP rate limiter rows in the hosting guide.
Large tool results are stored by the result renderer for every tool, resources/read returns plain data since protocol 2025-06-18, two PHPStan rules check MCP tool privileges, and strict Choice fields accept enum provider values, which makes category.type strict.
Developer Docs healthcheckStatus: Completed with |
MCP clients can log in to /api/_mcp with OAuth: discovery documents, tokens bound to the MCP resource, client registration, redirect rules, and troubleshooting for the setup. Sessions on /api/_mcp are bound to their principal, and the Admin API rate limit counts per user or integration. Tool results follow the negotiated protocol revision instead of the v6.8.0.0 feature flag, and the PHPStan privilege rule accepts the new McpToolRequiresNoPrivilege opt-out.
2 of 5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the developer- and operator-facing changes of MCP Iteration 4 (epic shopware/shopware#20866) for 6.7.17.0:
/api/_mcpwith OAuth: discovery through RFC 9728 and RFC 8414 metadata at path-suffixed well-known URIs, tokens bound to the MCP resource (RFC 8707) that work only on/api/_mcp,issin the authorization response (RFC 9207).Operators register clients in
shopware.api.oauth_clients; there is no dynamic client registration.The pages cover redirect rules, the Claude Code setup with
--callback-port, subdirectory rewrites, what an OAuth login may call (the approving user's allowlist, administrators unrestricted), and troubleshooting, including the misleadinginvalid_targetfrom an Administration built before the change./api/_mcpare bound to the principal that opened them; another principal gets404.mcp_admin_apirate limit counts per user or integration instead of per access token.v6.8.0.0feature flag.Since 2025-06-18 the text is the plain data and
structuredContentcarries the metadata for the model under_meta; before 2025-06-18 the deprecated{"success": …}envelope stays.A table lists which part of the result Claude Code, Codex, VS Code, Cursor, Gemini CLI and ChatGPT pass to the model.
resources/readreturns the format of the call that stored them.#[McpToolRequires]and the new#[McpToolRequiresNoPrivilege]; the Store API rule follows inherited methods.Choicefields accept values from enum providers, which is how extensions keep their own category types now thatcategory.typeis strict.Merge order: this branch builds on #2571 (6.7.16 MCP update), because both rewrite the same large-result paragraphs, so basing it on
mainwould conflict.Until #2571 is merged, this PR also shows its commits; only the last two commits belong here.
Merge it after #2571 and after the code PRs below.
Related links
shopware.mcpAdminToolMissingRequiresandshopware.mcpStoreApiToolAdminAcl,#[McpToolRequiresNoPrivilege]category.type, enum providers for strict choicesresources/references/adr/, and the configuration page links to itChecklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted..wordlist.txt(and sorted it) if spellcheck flags new legitimate terms.Notes
The code PRs are drafts, so this describes them as they are now.
Open points that may change the text:
structuredContentwith metadata ({"result": …, "_meta": …}) is still pending a decision in refactor(framework): render MCP tool results per protocol revision and offload them in the renderer shopware#21844.vendor/shopware/core/DevOps/StaticAnalyze/PHPStan/rules.neon) and thephpstan/phpstan-symfonyrequirement need a check against a real plugin setup.