Upgrade Notes
Upgrade to 2026.4.0
From the beta: open proposals
Proposals stored by the beta (up to v0.8.26-beta) predate Change Control: they are not moved onto change
sets during the upgrade. Before you upgrade, approve or reject every open proposal in the chat.
If open beta proposals are left, the migration Version20260902140000 stops and names how many there are.
Nothing has been dropped at that point: decide them first, or discard them with
DELETE FROM <table> WHERE branch_uuid IS NULL (the message names the table), then run the migrations again.
MCP server placeholders expand only MCP_* names
${NAME} placeholders in the url and headers of an agent's MCP servers now expand for variable names that
start with MCP_ and for names you list in the agent-server's new AGENT_SERVER_MCP_ENV_ALLOWLIST setting
(comma-separated). Any other name expands to an empty string, so an entry whose url depends on it is skipped.
If your agents use placeholders such as ${SALESFORCE_TOKEN}, rename the variable to MCP_SALESFORCE_TOKEN or add
its name to AGENT_SERVER_MCP_ENV_ALLOWLIST. The systemMessage of an agent expands no placeholder any more.
Proposals as change requests
- Run Change Control's migrations before the agent stores new proposals
(
bin/console doctrine:migrations:migrate --prefix 'Pimcore\Bundle\ChangeControlBundle'), then the agent bundle's own (--prefix 'Pimcore\Bundle\PimcoreAgentBundle'). - Every proposal stored from the upgrade on is a change request in Change Control's Reviews list, private to the user whose chat proposed it. Proposals stored before keep working in the chat and get no change request. See HITL Proposals.
AgentSessionServiceInterfacehas a new method,currentProposalOn(). A class of your own that implements the interface instead of extendingAgentSessionServiceadds it.- New endpoints:
GET,POST …/applyandPOST …/rejectunder/pimcore-studio/api/bundle/agent/proposals/change-sets/{id}, for the change request tab. - A custom proposal type needs no change: its proposals become change requests too, and its user decides them in the chat (Custom Proposal Types).
MCP endpoints and version coauthor
- [MCP] Changed: the endpoints
/pimcore-mcp/agent/{group}and/pimcore-mcp/agent/metaserve the built-in Pimcore Agent only. They accept the chat's MCP access token (pmcp_…, bound to an existing chat session) and answer403to every other credential: a personal access token, an OAuth token and a Studio session. External MCP clients connect through a configured MCP server of the Studio Backend bundle (/pimcore-mcp/studio/<slug>), which still accepts OAuth tokens and personal access tokens. Setups that point Claude Desktop, Cursor or a custom client at/pimcore-mcp/agent/*stop working: create a configured server and assign the tools there. Tools taggedpimcore.mcp_toolonly (nopimcore.studio_backend.mcp_tool) are not selectable on a configured server and so lose external access: the HITL proposal groups (*-write),pimcore-file-staging,pimcore-agent-templates,pimcore-task, the class editor proposal group (pimcore-class-editor-write), thedelete_class_definitiontool ofpimcore-class-editor-direct-write,pimcore-collab-tasks(Collab),data-onboarding(Data Onboarding) and the Copilot automation tools. See Built-in Pimcore MCP Servers. - [Version Coauthor] Changed: the coauthor type
mcp-clientand the client-claimed name from the MCPinitializehandshake are removed (CoauthorClientInfoReferenceHandler,@internal, is deleted). Direct writes through a configured MCP server are stamped by the Studio Backend bundle with the typemcp-serverand the server's slug; the chat keeps stampingagentand the agent's name. Versions that already carrymcp-clientkeep their value. The constructors ofMcpServerFactoryandMcpMetaServerFactorytake aMcpCallContextInterfaceinstead of the coauthor context and the$coauthorEnabledflag (the switchpimcore_agent.version_coauthor.enabledis unchanged). - [Version Coauthor] Changed:
update_assetno longer removescoauthorType/coauthorfrom its data itself. Inside an MCP tool call every save ignores a coauthor in its payload (Studio Backend rule), also when stamping is switched off. - [Requirements] The bundle requires
pimcore/studio-backend-bundle^2026.4(McpCallContextInterface).