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

#	Flow	Direction	Endpoint	Credential	Firewall / authenticator	Canonical detail
1	Chat + SSE stream	Browser → agent-server	/agent-server/api/chat, /agent-server/api/chat/:id	Pimcore session cookie (validated, cached)	agent-server auth middleware	Request Lifecycle, Authentication
2	Internal MCP tool calls	Agent-server → PHP	/pimcore-mcp/agent/*	Authorization: Bearer pmcp_…	pimcore_mcp → McpAccessTokenAuthenticator	MCP Integration
3	Session / proposal persistence	Agent-server → PHP	/pimcore-studio/api/bundle/agent/sessions|proposals	cookie (synchronous) / pmcp_… bearer (deferred)	pimcore_agent_bundle_api → SessionBridge, McpAccessToken	MCP Integration, Session Storage
4	External MCP tool calls	Agent-server ↔ 3rd-party	per mcpServers YAML	per-server (neither cookie nor pmcp_)	n/a (remote server's own auth)	MCP Integration
5	Config export + reload	PHP ↔ agent-server	…/configurations/export, /agent-server/api/admin/*	admin bearer (AGENT_SERVER_ADMIN_TOKEN)	PUBLIC_ACCESS + hash_equals (export)	Configuration System
6	Live cross-client sync	Agent-server → Mercure → browser	MERCURE_SERVER_URL (per-user topic)	publisher JWT (HS256, MERCURE_JWT_KEY)	hub validates private-update scope	Real-time Sync
7	LLM / inference calls	Agent-server → provider	provider baseUrl	per-provider byok (apiKey) / github token	provider's own auth	Authentication, 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. → 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

Credential	Minted / owned by	Used on flows	Lifetime
Pimcore session cookie (PHPSESSID)	Pimcore login	1, 3 (synchronous)	Pimcore session; validation cached AGENT_SERVER_AUTH_CACHE_TTL
MCP access token (pmcp_…)	studio-backend McpAccessTokenService, per chat session	2 (always), 3 (deferred)	Bundle-configured TTL (default 2h); refreshed/re-minted; revocable
Admin bearer (AGENT_SERVER_ADMIN_TOKEN)	Operator / deployment env	5	Static deployment secret
Mercure publisher JWT	Agent-server, in-process (MERCURE_JWT_KEY)	6	Per-publish, short-lived
Provider credential (byok / github)	Deployment config (inference.providers)	7	Per SDK session

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