Built-in Pimcore MCP Servers

The bundle ships a catalog of Pimcore operations exposed as Model Context Protocol tools, organised into tool groups. Each group is a streamable-HTTP MCP endpoint served at /pimcore-mcp/agent/<group>. Two kinds of client can consume them:

1. The built-in Pimcore Agent inside Studio - the normal case; an agent declares which groups it may use.
2. An external MCP-capable LLM client (Claude Desktop, Cursor, a custom integration) - pointed directly at the endpoints with a personal access token.

Both consume the same tools and are subject to the same Pimcore permissions. What differs is the credential and whether an interactive chat session exists (which some tools require - see below).

The built-in tool groups

All internal tools are registered via the pimcore.mcp_tool service tag. Endpoints follow the pattern /pimcore-mcp/agent/<group>.

Always-current list: run bin/console pimcore-agent:mcp:list-tools to see the live set of groups and tools registered in your installation. Add -v to also print the backing PHP class and method for each tool.

Data Objects

Group	Description	Tools
pimcore-data-objects-read	Read-only data object access	list_classes, get_class_definition, get_field_schema, get_data_object, get_queryable_fields, search_data_objects
pimcore-data-objects-write	Create objects + propose updates (HITL)	create_data_object, propose_data_object_update
pimcore-data-objects-direct-write	Direct updates (no user approval)	update_data_object

Assets

Group	Description	Tools
pimcore-assets-read	Read-only asset access with staging	get_asset, get_asset_queryable_fields, list_assets, search_assets, stage_asset
pimcore-assets-write	Propose asset metadata changes (HITL)	propose_asset_metadata_update
pimcore-assets-direct-write	Direct asset upload and update (no user approval)	update_asset, upload_asset

Documents

Group	Description	Tools
pimcore-documents-read	Read-only document access	get_area_brick, get_document, get_document_schema, list_target_groups, search_documents
pimcore-documents-write	Create documents and propose editable changes (HITL)	create_document, list_document_types, propose_document_update
pimcore-documents-direct-write	Direct editable updates (no user approval)	update_document

list_target_groups lives in the read group only. An agent that authors target-group variants needs read access anyway (to inspect the document before proposing), so a second registration in the write group would register the same tool twice. When the optional Pimcore personalization-bundle is not installed it returns {available: false, targetGroups: []} - see Document Schema → Target-group variants.

To get good edits on YOUR documents, author example fixtures for your areabricks and document templates. The LLM uses them to pattern-match a valid edit. See Extending → Template Examples for the dev workflow (two CLI commands + a coding-agent SKILL that automates authoring). The MCP tools work without fixtures, but small LLMs benefit substantially from worked examples.

Tags

Group	Description	Tools
pimcore-tags-read	Read-only tag access	get_element_tags, list_tags
pimcore-tags-write	Propose tag changes (HITL) and create tags	create_tag, propose_tag_assignment
pimcore-tags-direct-write	Direct tag assign/unassign (no user approval)	assign_tag, unassign_tag

Agent Templates

Group	Description	Tools
pimcore-agent-templates	Generate Twig page/snippet/partial templates and HITL-propose them	list_editables, propose_agent_template, propose_agent_template_deletion, list_agent_templates, list_thumbnail_configs
pimcore-file-staging	Stage developer-curated project files for reading. Auto-registered when the agent's allowedFileStagingSets is non-empty - do not list it in pimcoreMcpServers.	stage_file_set

See Agent Templates for the feature, and Configuration → File Staging / Configuration → Agent Templates for the file_staging and agent_templates reference.

Tasks

Group	Description	Tools
pimcore-task	End a headless agent task with its final, machine-readable result. Auto-injected only into a task-origin session - do not list it in pimcoreMcpServers / pimcoreMetaGroups; it never reaches a regular chat session.	finalize_task

See Features → Agent Tasks for the feature and Architecture → Agent Tasks for the mechanism that injects this group.

HITL vs. direct-write: the *-write groups create proposals the user must approve through the chat UI. The *-direct-write groups bypass that approval step - use them only for agents that run in trusted / automated contexts.

See Extending → Custom MCP Tools for how to add tools to existing groups or register new ones.

Using the tool groups

From the Pimcore Agent (inside Studio)

This is the primary path. An agent declares the groups it may use in its YAML via pimcoreMcpServers (schemas inline every turn) or pimcoreMetaGroups (behind the meta-tool). Calls are authenticated with the chat-scoped pmcp_… bearer, so the tools run with exactly the permissions of the user who started the chat, and HITL proposals surface as approval cards in the chat UI.

→ Configure this in Configuration → MCP Servers.

From an external LLM / MCP client

Yes - the groups are ordinary streamable-HTTP MCP servers, so any MCP-capable client can call them directly.

• URL. Point the client at https://<your-pimcore-host>/pimcore-mcp/agent/<group> - for example …/pimcore-mcp/agent/pimcore-data-objects-read. The meta-tool endpoint …/pimcore-mcp/agent/meta?groups=<a,b,c> exposes several groups behind the three generic meta tools.
• Authentication. External clients use a static Personal Access Token (PAT), sent as Authorization: Bearer <token>. PATs are configured in the Studio Backend bundle under pimcore_studio_backend.mcp.authentication.tokens as a Pimcore-username → token-list map; the request then runs as that user. (This is a different credential from the agent's dynamic pmcp_… bearer, which is minted per chat session and is not something you configure by hand.)
• Permissions. Identical to the mapped user's Pimcore permissions - workspace ACLs and role permissions apply. There are no MCP-specific scopes.

{
  "mcpServers": {
    "pimcore-data-objects": {
      "url": "https://your-pimcore-host/pimcore-mcp/agent/pimcore-data-objects-read",
      "headers": { "Authorization": "Bearer <your-PAT>" }
    }
  }
}

Chat-session caveat. Some tools require an interactive chat session and are therefore not usable from an external client: every HITL proposal tool (propose_*) and the staging tools (stage_asset, stage_file_set) resolve the current chat session from the dynamic pmcp_… token, which a PAT does not carry. From an external client, use the read groups and the *-direct-write groups; the HITL *-write groups and pimcore-file-staging only work for the built-in Pimcore Agent.

For the firewall, the PAT configuration, and how the three MCP authenticators relate, see the Studio Backend bundle's MCP Server Infrastructure documentation. For the internal (pmcp_…) credential and token lifecycle, see Architecture → MCP Integration and Architecture → Authentication.

Related docs

• Configuration → MCP Servers - how an agent declares MCP access (the YAML keys).
• Architecture → MCP Integration - transport, auth forwarding, meta-tool mechanism.
• Architecture → Communication Flows - where MCP calls sit among all flows.