Personal Agent Protocol for Magento 2 in three stages: discovery with poppy.json, guest UCP with a verified Poppy-Session, and signed-in agents, which need an OAuth 2 issuer Magento does not ship

Personal Agent Protocol for Magento 2: What to Ship

This article leads with what a Magento 2 merchant has to ship now that personal agents such as Meta’s Muse look for a poppy.json file on every store they visit, and every Shopify store already publishes one without any setup. It is written for the tech lead who has to decide how far to go: one discovery file, a guest shopping API behind it, or signed-in agents.

TL;DR — Publish a /.well-known/poppy.json without sign-in that points at your storefront and, if you run one, a Universal Commerce Protocol (UCP) profile. That makes a Magento 2 store discoverable to Personal Agent Protocol (Poppy) agents with one module, one config switch and one deploy, and no checkout risk. Signed-in agent shopping is a separate project: Magento has no OAuth 2 authorization server and its customer tokens have no refresh token, so it needs an external identity provider first.

Why this matters now

Sierra and Meta released Poppy 1.0 on 13 November 2026, with more than 100 partners. Three facts from the release decide the timing for Magento:

  • Shopify turned it on for every merchant. In Sierra’s words, "every Shopify store now automatically publishes a Poppy file, so merchants don’t need to do any extra implementation."
  • Muse checks for it first. Meta’s Muse "automatically looks for Poppy first on every site it visits."
  • Magento has nothing. Adobe has announced UCP and the OpenAI Agentic Commerce Protocol for Adobe Commerce, not Poppy. On 19 November 2026 there was a Poppy plugin for WooCommerce and a package for Sylius, and none for Magento 2.

A Magento store without a Poppy file still works for an agent that drives a browser. It just drops out of the protocol path that agent tries first, and competes on a scraped HTML page against Shopify stores that answer with a structured description of themselves.

What Poppy asks of a store

Poppy covers who the agent is and what the company allows. It does not do shopping: carts and checkout stay with UCP, which Poppy links to through an extension. The split looks like this:

flowchart LR
    A[Personal agent<br/>Muse, others] -->|GET| P["/.well-known/poppy.json"]
    P -->|web| W[Storefront]
    P -->|extensions.ucp| U["/.well-known/ucp<br/>UCP profile"]
    P -->|tasks.endpoint| T["/poppy/v1/tasks<br/>Poppy-Session verified"]
    P -.->|auth, later| O[OAuth 2 issuer<br/>signed-in agents]

The baseline is one JSON file at /.well-known/poppy.json, served over HTTPS on the store’s own host. The schema requires two fields, protocol_version and organization, plus at least one way in: web, apis or agent (a conversation endpoint). organization.domain has to match the host the file was fetched from, so a multi-website Magento install needs one file per host, not one per installation.

The official company kit splits the work into milestones: Foundation, Interfaces, Sign-in, and optional Extensions. A company that offers only its website can stop after Foundation, with no auth section at all. That is the cheap end, and for most Magento stores it is the right place to start.

The tradeoff: three adoption stages for Magento 2

Stage 1: discovery only

Publish poppy.json with organization, web and, if a UCP module serves /.well-known/ucp on the same host, "extensions": {"ucp": [{"version": "1"}]}. The agent learns the store exists, that it may use the website signed out, and where the shopping API lives.

  • Strengths: a module and a deploy. No customer data, no payment path, nothing an agent can change. The validator’s Foundation milestone passes.
  • Costs: the file can lie. If it advertises UCP while the UCP module is switched off, agents follow a dead link. Generate it from store config and live module state, never by hand.

Stage 2: guest shopping through UCP, plus the Session header

Behind the discovery file sits a guest UCP service: catalog search and lookup first, checkout later. On top, Poppy endpoints of your own start verifying the Poppy-Session header: a short-lived JSON Web Token (JWT) the agent signs for each request, chained to a delegation from the agent’s operator.

  • Strengths: agents can search the catalog through an API instead of scraping it, and the store can tell which agent is calling and refuse the ones it blocks. A read-only UCP catalog carries no payment risk.
  • Costs: this is where outbound HTTP starts. Verifying a Session means fetching the agent’s metadata and keys from a URL the agent chose, which is a server-side request forgery (SSRF) surface. Plan for HTTPS-only fetches, no redirects, size and time caps, and DNS pinning. Checkout through UCP adds idempotency and payment questions that deserve their own project.

Stage 3: signed-in agents

Signed-in agents act on a customer account: order history, reorders, approvals. Poppy builds this on OAuth 2, and Magento 2 does not have the pieces:

Poppy expectsMagento 2 ships
An OAuth 2 authorization server with refresh tokens and published metadataOAuth 1.0a for admin integrations; a customer token endpoint that returns one bearer string, no refresh token
Scopes the customer approves on a consent pageResource ACL for integrations, no customer-chosen scopes
An OpenAPI 3.x description for apis entriesA REST schema generated as Swagger 2.0 (Magento\Webapi\Model\Rest\Swagger::SWAGGER_VERSION)
  • Strengths: the full agent experience, the one Shopify customers will get through Shop Pay.
  • Costs: an external identity provider such as Keycloak, Auth0 or Entra ID, a mapping from its tokens to Magento customers, an OpenAPI 3 document written by hand for the endpoints you expose, and a consent page. Budget it as a separate project, not as a module update.

A working example: the stage 1 and 2 module

Here is a working example on Magento Open Source 2.4.8-p5 with PHP 8.4: brocode/module-poppy, MIT licensed, published on GitHub and Packagist. It serves poppy.json, links a UCP profile when one is really there, verifies the Poppy-Session header on a tasks endpoint, and since 1.1.0 takes feedback reports from agents. It implements no UCP itself; the test setup pairs it with angeo/module-ucp and angeo/module-ucp-catalog for a read-only guest catalog.

ddev composer require brocode/module-poppy
ddev exec php bin/magento module:enable BroCode_Poppy
ddev exec php bin/magento setup:upgrade
ddev exec php bin/magento config:set brocode_poppy/general/enabled 1
ddev exec php bin/magento cache:flush

Where the file comes from

The module registers its own frontend router for /.well-known/poppy.json, the same pattern the angeo UCP modules use for /.well-known/ucp, so it has no hard dependency on any UCP module. The document is built from store config at request time:

  • organization.domain comes from the store’s secure base URL. Without an HTTPS base URL, the module publishes nothing and the route answers 404.
  • organization.name falls back from the module setting to the Store Information name, then to the store’s frontend name.
  • A logo goes in only when its URL is HTTPS.
  • extensions.ucp goes in only when the admin switch is on and a known UCP module is enabled and switched on for that store. The list of UCP modules is a di.xml argument (module name → its on/off config path), so a different UCP module needs no code change.

On the sandbox, with sessions switched on, the response is:

{
  "protocol_version": "1.0",
  "organization": {
    "name": "Main Website Store",
    "domain": "magento2-sandbox.ddev.site"
  },
  "web": {},
  "tasks": {
    "endpoint": "https://magento2-sandbox.ddev.site/poppy/v1/tasks"
  },
  "extensions": {
    "ucp": [{ "version": "1" }]
  }
}

It goes out as application/json with Cache-Control: max-age=300, public, so a config change shows up after a cache flush, not instantly.

Verifying the Poppy-Session header

The tasks endpoint, GET /poppy/v1/tasks, is the smallest resource the spec defines. It exists so the store has one place where a signed-out agent proves who it is. Without a valid header it answers 400 {"error":"invalid_session"}. With one, the checks run in this order:

1. Cheap checks on the unverified token first: type, audience, method, URL, issue time, session ID and Poppy-Version. A malformed request costs no outbound traffic.

2. The admin blocklist and optional allowlist of agent IDs.

3. Fetch the agent’s metadata and keys: HTTPS only, no redirects, a 3-second timeout, a 64 KB cap, and the resolved IP pinned for the connection, so the agent cannot point Magento at an internal host. Fetches on a cache miss are capped per store per minute; above the cap the endpoint answers 429.

4. Verify the delegation (ES256 or PS384) and the Session JWT (ES256). Magento already ships the code for both algorithms in Magento\Framework\Jwt\JwtManagerInterface, so the module adds no dependency. That library checks signatures only; the claim checks are the module’s own.

5. Record the Session in a table, keyed by agent and session ID, so an ended Session keeps answering session_ended. A cron job removes idle rows after 30 days.

The module never issues access tokens. A request with Authorization: Bearer … gets 401 with WWW-Authenticate: Bearer error="invalid_token", which is what the spec asks of a company without an issuer.

Feedback: what agents could not do in the shop

The spec lets an agent report a task it could not finish through the protocol, such as "Pay with a gift card", with a short description of what it tried. Since version 1.1.0 the module takes those reports at POST /poppy/v1/feedback and lists that endpoint in the tasks response:

{
  "task": "Pay with a gift card",
  "description": "The checkout offers no field for a gift card code."
}
  • A report needs a valid Poppy-Session, so every stored report has a verified agent behind it. The User ID is not stored.
  • task takes 1 to 200 characters and description 1 to 2000. Anything else gets 400 {"error":"invalid_request"}; an accepted report gets 202 with no body.
  • Each agent can send 50 reports an hour and a store view takes 500 an hour from all agents by default; above that the endpoint answers 429 with Retry-After.
  • Reports land in an admin grid under Reports > Poppy > Agent Feedback and are deleted after 90 days.

For a merchant this is the most direct signal the protocol offers: a list of what agents tried and failed to do in this shop. Treat the text as untrusted input: an agent writes it, and the grid shows it escaped.

What to skip

  • A static poppy.json in pub/.well-known/. It drifts from store config the first time someone renames the store or switches a UCP module off, and it cannot serve a different organization.domain per website.
  • Building an OAuth 2 server inside Magento to reach stage 3 faster. Use the identity provider you already run, and map its tokens to customers.
  • Exposing the admin REST API as an apis entry. Wrong audience, the wrong schema version, and an admin token must never reach an agent.
  • Advertising UCP checkout before payment and idempotency are tested. An agent that fails at checkout costs more than one that never offered it.
  • Verifying the header on every storefront page. The spec allows it, but a page that varies by a signed header is a page that cannot come from the full-page cache. Verify on the Poppy endpoints first and leave the pages cached.

Verification

Check the file and the headers first:

curl -s https://www.example.com/.well-known/poppy.json | jq .
curl -sI https://www.example.com/.well-known/poppy.json | grep -iE '^(content-type|cache-control)'
curl -s https://www.example.com/poppy/v1/tasks

The last call should answer {"error":"invalid_session"}: the endpoint exists and refuses an unsigned request. A POST without a header to /poppy/v1/feedback answers the same once feedback is switched on.

Then run the validator from the official company kit. It needs Node.js, generates its own test agent, and checks both the file and a live Session against the tasks endpoint:

node validate/index.ts check https://www.example.com \
  --probe https://www.example.com/poppy/v1/tasks --probe-session

Against the sandbox it exits 0: Foundation 38 passed and 0 failed, Interfaces 2 passed and 0 failed, and all 24 Session checks pass. Two checks stay skipped by the validator’s design: one needs a conversation, feedback or browser endpoint, and one only applies to a company that issues tokens. The sign-in milestone stays skipped because there is no issuer. A local DDEV run also needs --allow-private-addresses and the mkcert root in NODE_EXTRA_CA_CERTS, and the module needs brocode_poppy/allow_private_addresses in app/etc/env.php. That setting is deployment config on purpose, never an admin switch, and never belongs on production.

These validator figures are from version 1.0.0; the feedback endpoint added in 1.1.0 is covered by unit tests but has not had a validator run yet. The module itself carries 209 unit tests, PHPStan level 8 and the Magento 2 coding standard with 0 errors and 0 warnings.

Related modules

If you want this as a drop-in, see the Magento 2 Poppy module (source on GitHub). For the conversation channel Poppy can point to, the Magento 2 MCP customer chatbot covers the store-side agent, and MCP security for e-commerce covers scopes and irreversible actions, the same questions stage 3 raises. For how agents get past bot protection in the first place, see the Magento bot protection proxy.

Related reading

Related Topics

← Previous

Written in collaboration with AI (Claude, by Anthropic). Ideas, verification, and accountability are mine; research and drafting are AI-assisted. Full disclosure → · Found an error? Tell me.