Skip to main content
Version: 2026.2

Communication Flows

The Pimcore Agent Bundle is a distributed system: a browser (Pimcore Studio), the Node.js agent-server, the Pimcore PHP backend (bundle API + internal MCP servers + config export), a Mercure hub, one or more LLM inference providers, and optionally external MCP servers. This page is the map: it enumerates every runtime communication flow and shows, for each, which credential authenticates it and where the full detail lives.

Each flow's authentication mechanics are documented in exactly one canonical page; this overview links to them rather than repeating them.

System map​

Browser / Pimcore Studio
│ ▲
(1) │ │ (6) Mercure SSE (live updates to the user's own tabs)
cookie │
▼ │
┌─────────────────┐ (7) byok / github ┌─────────────────────────┐
│ Agent-server │ ───────────────────────▶ │ LLM inference provider │
│ (Fastify) │ └─────────────────────────┘
└──┬───┬───┬───┬──┘ (4) per-YAML creds ┌─────────────────────────┐
│ │ │ └─────────────────────────────▶│ External MCP servers │
│ │ │ └─────────────────────────┘
│ │ │ (6) publisher JWT ┌───────────┐
│ │ └────────────────────▶│ Mercure │──▶ user's own tabs (private per-user topic)
│ │ │ hub │
│ │ (5) admin bearer └───────────┘
│ └──────────────▶ PHP: config export / reload
│
├─ (2) Bearer pmcp_ ──────────▶ PHP internal MCP (pimcore_mcp firewall)
│
└─ (3) cookie (sync) /
pmcp_ bearer (deferred) ▶ PHP bundle-API (pimcore_agent_bundle_api firewall)
sessions | proposals

The flows at a glance​

#FlowDirectionEndpointCredentialFirewall / authenticatorCanonical detail
1Chat + SSE streamBrowser → agent-server/agent-server/api/chat, /agent-server/api/chat/:idPimcore session cookie (validated, cached)agent-server auth middlewareRequest Lifecycle, Authentication
2Internal MCP tool callsAgent-server → PHP/pimcore-mcp/agent/*Authorization: Bearer pmcp_…pimcore_mcp → McpAccessTokenAuthenticatorMCP Integration
3Session / proposal persistenceAgent-server → PHP/pimcore-studio/api/bundle/agent/sessions|proposalscookie (synchronous) / pmcp_… bearer (deferred)pimcore_agent_bundle_api → SessionBridge, McpAccessTokenMCP Integration, Session Storage
4External MCP tool callsAgent-server ↔ 3rd-partyper mcpServers YAMLper-server (neither cookie nor pmcp_)n/a (remote server's own auth)MCP Integration
5Config export + reloadPHP ↔ agent-server…/configurations/export, /agent-server/api/admin/*admin bearer (AGENT_SERVER_ADMIN_TOKEN)PUBLIC_ACCESS + hash_equals (export)Configuration System
6Live cross-client syncAgent-server → Mercure → browserMERCURE_SERVER_URL (per-user topic)publisher JWT (HS256, MERCURE_JWT_KEY)hub validates private-update scopeReal-time Sync
7LLM / inference callsAgent-server → providerprovider baseUrlper-provider byok (apiKey) / github tokenprovider's own authAuthentication, Inference Providers

How authentication works, flow by flow​

(1) Chat + SSE - session cookie. The browser sends its Pimcore PHPSESSID cookie; the agent-server's auth middleware validates it once against GET /pimcore-studio/api/user/current-user-information and caches the resolved identity (keyed by sha256(cookie), TTL AGENT_SERVER_AUTH_CACHE_TTL). The agent-server owns no users - it borrows Pimcore's. → full detail: Authentication → User session cookie.

(2) Internal MCP tool calls - pmcp_ bearer. When an agent calls a Pimcore tool, the agent-server sends a chat-scoped MCP access token (Authorization: Bearer pmcp_…) to /pimcore-mcp/agent/*. The pimcore_mcp firewall's McpAccessTokenAuthenticator resolves it to the chat initiator's Pimcore User, so the tool runs with exactly that user's permissions. The cookie is never forwarded here, and no other credential is accepted on these endpoints (external clients use a configured MCP server at /pimcore-mcp/studio/<slug>). → full detail: MCP Integration → Authentication forwarding.

(3) Session / proposal persistence - cookie or bearer. The agent-server persists chat state through the bundle API. Synchronous in-request work (create session, list, proposals) reuses the validated session cookie; deferred work that must outlive the browser session (the post-turn persistence flush) uses the pmcp_… bearer. Both are accepted by the dedicated pimcore_agent_bundle_api firewall (SessionBridge → McpAccessToken; PAT intentionally excluded). → full detail: MCP Integration → Authentication forwarding and Session Storage.

(4) External MCP servers - per-YAML. Third-party MCP servers configured under mcpServers receive neither the cookie nor the pmcp_ bearer; they authenticate however their YAML defines (e.g. a static header). → full detail: MCP Integration → External MCP servers.

(5) Config export + reload - admin bearer. The agent-server fetches the merged config from PHP on startup and on every reload using the shared AGENT_SERVER_ADMIN_TOKEN; the export endpoint is verified with hash_equals and bypasses the user-session firewall via a PUBLIC_ACCESS rule. Operators hit the same-token /agent-server/api/admin/* endpoints to trigger reloads. → full detail: Configuration System → Export endpoint contract.

(6) Live cross-client sync - publisher JWT. Each turn event is published to Studio's per-user Mercure topic with a narrow HS256 publisher JWT signed by the shared MERCURE_JWT_KEY. It only publishes; private updates mean the hub delivers events to the owning user's tabs only. → full detail: Real-time Sync → Live delivery.

(7) LLM / inference calls - per provider. Each configured inference provider carries its own auth_mode: byok supplies an apiKey, github sets a session gitHubToken. Credentials are resolved once per SDK session. → full detail: Authentication → Per-provider LLM authentication.

Credentials at a glance​

CredentialMinted / owned byUsed on flowsLifetime
Pimcore session cookie (PHPSESSID)Pimcore login1, 3 (synchronous)Pimcore session; validation cached AGENT_SERVER_AUTH_CACHE_TTL
MCP access token (pmcp_…)studio-backend McpAccessTokenService, per chat session2 (always), 3 (deferred)Bundle-configured TTL (default 2h); refreshed/re-minted; revocable
Admin bearer (AGENT_SERVER_ADMIN_TOKEN)Operator / deployment env5Static deployment secret
Mercure publisher JWTAgent-server, in-process (MERCURE_JWT_KEY)6Per-publish, short-lived
Provider credential (byok / github)Deployment config (inference.providers)7Per SDK session

External MCP credentials (flow 4) are defined entirely by the operator's mcpServers YAML and are outside this table.