Shopify switched the Personal Agent Protocol (Poppy) on for every store, and Meta’s Muse looks for it first on every site it visits. This module gives a Magento 2 store the same thing: a /.well-known/poppy.json built from store config, a link to the store’s UCP profile when one is really there, and an endpoint that verifies the signed Poppy-Session header agents send. Best fit for stores that want to be found by personal agents now, without opening sign-in or checkout to them.
Typical impact: one config switch and one deploy to a store that passes the official Poppy validator, with Foundation 38 passed and 0 failed, and no customer data or checkout exposed to agents.
Who it is for
- Magento Open Source stores competing with Shopify stores that publish a Poppy file automatically.
- Stores already running a UCP module such as
angeo/module-ucp, which want personal agents to find that profile through the protocol they check first. - Agencies and tech leads who need a tested baseline for agent discovery before they scope signed-in agent shopping.
Who should skip it
- Stores that need agents to sign in, see order history or act on a customer account. That needs an OAuth 2 issuer, which this module does not provide.
- Stores without an HTTPS base URL per store view. Without one the module publishes nothing.
- Teams that only want a UCP catalog. Install a UCP module; Poppy only points to it.
What it does
/.well-known/poppy.jsonper host.organization.domaincomes from the store’s secure base URL, so every website gets its own file with the domain the protocol requires. The name falls back from the module setting to Store Information to the store name. Cached publicly for 300 seconds.- An honest UCP link.
extensions.ucpappears only when the admin switch is on and a known UCP module is enabled and switched on for that store. Switch the UCP module off and the link disappears, so agents never follow a dead profile. Other UCP modules are onedi.xmlentry. - Signed-out agent Sessions.
GET /poppy/v1/tasksverifies thePoppy-SessionJWT and its delegation (ES256 or PS384) with Magento’s own JWT code, no new dependency. Agent metadata fetches are HTTPS only, size and time capped, and pinned to the resolved IP. An admin blocklist and allowlist decide which agents get in. - Agent feedback. Agents report tasks they could not do in the shop at
POST /poppy/v1/feedback, with a verified Session. Reports appear in an admin grid under Reports > Poppy > Agent Feedback, capped at 50 per agent and 500 per store view per hour, and deleted after 90 days. - No tokens, no sign-in. The module never issues access tokens and refuses Bearer tokens with the error the spec asks for.
Before and after
Before
/.well-known/poppy.jsonanswers 404, so a personal agent falls back to scraping the storefront.- A UCP profile, if installed, is only found by agents that already know to look for it.
- The store cannot tell which agent is calling.
After
- Personal agents find the store’s name, domain, website and UCP profile through one file.
- The file follows store config and the UCP module’s on/off state, per website.
- Agents prove who they are with a signed Session; blocked agents get
invalid_session. - The merchant sees which tasks agents tried and could not finish, in an admin grid.
Installation
composer require brocode/module-poppy
bin/magento module:enable BroCode_Poppy
bin/magento setup:upgrade
bin/magento cache:flush
Then switch it on under Stores > Configuration > General > Personal Agent Protocol (Poppy): Publish /.well-known/poppy.json for discovery, Accept Personal Agent Sessions for the tasks endpoint, Accept Feedback Reports for the feedback endpoint, Advertise UCP when a UCP module serves /.well-known/ucp. setup:upgrade adds two tables, brocode_poppy_session and brocode_poppy_feedback; daily cron jobs remove idle Sessions and reports older than 90 days.
Compatibility
- PHP 8.2 or later
- Magento 2.4 Open Source; tested on 2.4.8-p5 with PHP 8.4
- Optional:
angeo/module-ucp+angeo/module-ucp-catalogfor the UCP profile (tested); other UCP modules throughdi.xml - The storefront has to run on HTTPS
FAQ
Does this make my Magento store work with Meta’s Muse?
It publishes the file Muse looks for first and passes the official validator. Muse then knows the store, its website and its UCP profile. Buying through an agent still depends on what the UCP module behind it offers.
Does the module implement UCP?
No. It links to a UCP profile served by another module and only lists it while that module is switched on for the store.
Can agents sign in to customer accounts with it?
No. Poppy sign-in needs an OAuth 2 authorization server with refresh tokens and consent, which Magento 2 does not ship. The module covers the signed-out part of the protocol.
How do I check it works?
curl -s https://<host>/.well-known/poppy.json returns the document, and curl -s https://<host>/poppy/v1/tasks answers {"error":"invalid_session"} without a signed header. The validator from the official company kit then checks a live Session end to end.
What does the agent feedback show?
One row per report: date, store view, the agent’s client ID, the task in a short phrase and what the agent tried. The User ID is not stored, and the text is shown escaped because an agent wrote it.
Does it slow down storefront pages?
No. Storefront pages do not check the Poppy-Session header and stay fully cached. Only the Poppy endpoints do any verification.
Related reading
- Personal Agent Protocol for Magento 2: What to Ship: the article behind the module, with the three adoption stages, what Magento lacks for signed-in agents, and the validator run.
- Magento 2 MCP customer chatbot: the store-side agent a Poppy file can point to later.
- Personal Agent Protocol 1.0 specification: the protocol itself.