Skip to main content
Version: 2026.1

MCP Servers

This page covers how to configure an agent's MCP tool access. For the catalog of built-in Pimcore tool groups and how to consume them (from the built-in Pimcore Agent or an external LLM client), see Features → Built-in Pimcore MCP Servers. For the architectural overview - transport, authentication, meta-tool - see Architecture → MCP Integration.

The three configuration keys​

Each agent YAML can use three independent keys to declare MCP access. An agent uses any combination of the three.

KeyTargetsSyntax
pimcoreMcpServersInternal tool groups, schemas inline in every turnList of group names
pimcoreMetaGroupsInternal tool groups, behind the meta-toolList of group names
mcpServersThird-party HTTP serversMap of server name → {type, url, headers, tools}

Examples:

pimcoreMcpServers:
  - pimcore-data-objects-read
  - pimcore-data-objects-write

pimcoreMetaGroups:
  - pimcore-tags-read
  - pimcore-assets-read

mcpServers:
  pimcore-datahub:
    type: http
    url: ${MCP_PIMCORE_URL}
    headers:
      Authorization: "Bearer ${MCP_PIMCORE_TOKEN}"
    tools: "*"

For the mechanism behind the meta-tool and how internal servers authenticate, see Architecture → MCP Integration.

Internal-server authentication knob​

Internal Pimcore MCP servers are reached with a per-chat-session bearer token (Authorization: Bearer pmcp_…). The only operator-facing setting is its lifetime:

pimcore_agent:
    chat_session_token:
        ttl: 7200      # seconds, default 7200 (2 h), minimum 60

PHP is the single source of truth - the value is returned alongside the bearer in every POST /bundle/agent/sessions and POST /bundle/agent/sessions/{id}/mcp-token response. The agent-server reads it from the response and uses it to pace its server-driven refresh timer: while a task is running, TaskRunner calls refreshToken every max(60s, tokenTtlSeconds/2). Operators can keep the TTL short without risking long-running or overnight turns - the server refreshes independently of user interaction or cookie validity. The TTL is a sliding window; the per-turn user-interactive refresh also extends it on every chat turn.

(No agent-server env var to keep in sync - the PHP config is the only place to set this.)

See Architecture → MCP Integration → Token lifecycle.

Environment variable interpolation (third-party only)​

mcpServers URLs and header values support ${VAR_NAME} placeholders. They are resolved on the agent-server side at session-resolve time using the agent-server container's environment - not the Pimcore PHP container's environment. Set these variables in .env.local, which is loaded into the agent-server container via Docker Compose's env_file directive.

mcpServers:
  external-api:
    type: http
    url: ${MY_API_URL}
    headers:
      Authorization: "Bearer ${MY_API_TOKEN}"
    tools: "*"

If any placeholder in an MCP entry is unset at resolve time, the entire entry is silently skipped - the server is not registered, and the agent runs without it. This lets you keep optional integrations in a shared YAML without breaking agents when the credentials are absent.

Pimcore-internal MCP servers (pimcoreMcpServers, pimcoreMetaGroups) do not use env var interpolation. Their URLs are built from PIMCORE_INTERNAL_URL + a well-known prefix, and authentication is handled by the chat-scoped pmcp_… bearer token, not by a static or user-session credential.

Built-in Pimcore tool groups​

The catalog of built-in groups (Data Objects, Assets, Documents, Tags, Agent Templates, …), the tools in each, the HITL-vs-direct-write distinction, and how to consume the groups from the built-in Pimcore Agent or an external LLM client are documented in Features → Built-in Pimcore MCP Servers.

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.

The group names you place under pimcoreMcpServers / pimcoreMetaGroups come from that catalog. To add tools to an existing group or register a new one, see Extending → Custom MCP Tools.