Skip to main content
Version: Next

Version Coauthor

Every element save that an agent performs is attributed twice: the version's user stays the human who owns the chat session, and the version additionally carries a coauthor that names the agent. This makes agent-driven changes auditable in the Versions tab of Pimcore Studio, which shows a "Co-authored by" tag on every stamped version.

What gets stored​

FieldValue
coauthorTypeagent
coauthorThe agent name of the chat session, for example data-management

The agent name comes from the persisted chat session (AgentSession::agentName), resolved through the trusted MCP token binding. For MCP tool calls the token reference identifies the session; for proposal approvals the session id comes from the proposal payload. In both cases the session lookup is scoped to the authenticated user, so a coauthor can only ever name an agent from one of the user's own sessions.

When stamping happens​

  • MCP tool calls: every request authenticated with a chat-session MCP token activates the coauthor context for the duration of the request. All element writes performed by MCP tools during that request stamp their versions, including tools added in the future.
  • HITL proposal approvals: when a user approves a proposal, the resolver applies the change with the coauthor context active for the session that produced the proposal.

Saves performed by the same user outside a chat session are not stamped, and stamping never overrides a coauthor that was set explicitly. Bulk writes that run through asynchronous execution-engine jobs are outside the request scope and are not stamped.

External MCP clients​

External MCP clients (Claude Desktop, Cursor, or a custom orchestrator authenticated with a personal access token) reach the same /pimcore-mcp/ write tools without a chat session. Their writes are stamped with a distinct coauthor type:

FieldValue
coauthorTypemcp-client
coauthorThe client name from the MCP initialize handshake, for example Claude Desktop

The client name is entirely client-claimed: any MCP client can send any name at initialize. Treat it as informational, not verified identity. The value is sanitized before it is stored: trimmed, stripped of control characters, and truncated to 100 characters. A missing or empty name is not stamped.

Internal chat sessions always take precedence. If a request already carries an agent coauthor from McpCoauthorSubscriber, the handshake-derived stamp never applies. Tool payloads cannot set the coauthor either: update_asset strips any coauthorType/coauthor keys from its JSON payload before it reaches the patch service, so an MCP client cannot claim an arbitrary coauthor through tool arguments.

Configuration​

Stamping is enabled by default. Disable it project-wide:

pimcore_agent:
    version_coauthor:
        enabled: false