Personal Agent Protocol · /.well-known/poppy.json

Poppy.json Validator & Personal Agent Protocol Guide

Shopify just enabled /.well-known/poppy.json across merchant stores for Personal Agent Protocol (Poppy 1.0). Validate your manifest, spot Shopify 0.4 vs 1.0 compatibility gaps, generate a clean config, and verify AI agent accessibility.

What happened

Following the Poppy 1.0 release (Nov 13, 2026), Shopify enabled /.well-known/poppy.json across standard Online Stores in 175+ countries, while personal agents like Meta Muse check this file first.

Poppy vs UCP split

Poppy (/.well-known/poppy.json) handles agent discovery, session tracking, and OAuth consent. UCP (/.well-known/ucp) handles product search, cart, and checkout actions.

Headless & SaaS note

Custom or headless Shopify storefronts often still return 404 for /.well-known/poppy.json and must serve the manifest explicitly over HTTPS with at least one channel.

Client-side Poppy 1.0 Inspector

Validate your /.well-known/poppy.json manifest

Load preset:
Fetch live store file:

curl -sS -i https://www.northwindgoods.com/.well-known/poppy.json

Validation result
Poppy 1.0 ready
9 Pass0 Warn0 Error
JSON

Valid JSON document syntax.

protocol_version

Poppy protocol_version "1.0" meets the v1.0 backward-compatible baseline.

organization.name

Organization name "Northwind Goods" is present.

organization.domain

Organization domain "www.northwindgoods.com" is a valid hostname.

channels

Interaction channels declared: agent, web.

agent.protocols

1 agent protocol endpoint(s) validated with HTTPS and descriptions.

web

Website browsing channel configured cleanly.

auth.scope_hints

OAuth scope_hints specify valid reversibility and personal_data flags.

extensions

Declared extension(s): ucp.

Poppy 1.0 Schema Reference

Key fields in /.well-known/poppy.json

Poppy Section 3.1 requires every URL in the manifest to use https:// and at least one interaction channel (agent, apis, or web).

FieldRequirementPurpose & compliance details
protocol_versionRequiredString in major.minor format ("1.0"). Note: Shopify's initial rollout serves "0.4".
organizationRequiredObject with display name, bare domain matching the serving host, and optional HTTPS logo_uri.
agent.protocols[]ChannelLists conversation endpoints (type such as ucp or poppy, HTTPS endpoint, and description required in 1.0).
apis[]ChannelProgrammatic contracts (type: openapi or mcp, HTTPS url, and short description).
webChannelEmpty {} permits signed-out visitor browsing; set disabled: true to steer agents to APIs instead.
auth.scopes & scope_hintsOptionalSupplements OAuth metadata with human-readable scopes, changes ("none" | "reversible" | "irreversible"), and personal_data boolean.
extensionsOptionalStandard extensions include ucp, operations, disclosures, browser-control, and mediated-sign-in. Custom keys need a domain prefix.

AI agent accessibility checklist for Shopify & SaaS sites

Publishing a valid manifest is only half the setup. Make sure personal agents and answer engines can actually reach your endpoints and verify your facts.

Serve /.well-known/poppy.json over HTTPS with 200 JSON

Headless Shopify, Hydrogen, Next.js, and Cloudflare Worker sites do not inherit Shopify's hosted Online Store manifest automatically. Return Content-Type: application/json without login walls.

Do not block verified agent fetches at the WAF or robots layer

Allow /.well-known/* discovery endpoints in CDN firewall rules and verify OAuth protected-resource metadata (/.well-known/oauth-protected-resource) matches organization.domain.

Pair agent endpoints with machine-readable pages and FAQPage schema

Discovery protocols let agents interact with your store, but answer engines still cite public product specs, llms.txt, comparison tables, and FAQPage JSON-LD when deciding which brand to recommend.

Plan for the Shopify 0.4 -> Poppy 1.0 schema transition

Early Shopify manifests use protocol_version "0.4" and omit description inside agent.protocols. Custom manifests you publish directly should target "1.0" with explicit descriptions.

Frequently asked questions

What is /.well-known/poppy.json?

It is the discovery manifest for the Personal Agent Protocol (Poppy), an open Apache 2.0 standard led by Sierra and Meta. It tells personal AI agents who owns the domain, how to establish a verified session or OAuth sign-in, and which agent, API (MCP/OpenAPI), UCP commerce, or web channels are supported.

Did Shopify enable poppy.json automatically for merchants?

Yes, for standard Shopify Online Store domains following the Poppy 1.0 rollout in November 2026. However, headless or custom-hosted storefronts often still return 404 and need to host /.well-known/poppy.json themselves.

Why does this validator warn on Shopify's 0.4 manifest?

Live Shopify stores initially serve protocol_version "0.4" and omit the description field inside agent.protocols. Under the finalized Poppy 1.0 specification, description is required on agent.protocols items and 0.4 is pre-1.0.

How does poppy.json relate to llms.txt and AI visibility (GEO)?

They solve complementary layers. llms.txt and structured pages (FAQPage, direct answers, comparisons) help answer engines understand and cite your brand in search answers. poppy.json and UCP tell personal AI agents how to interact, authenticate, and transact with your business.

Does validating poppy.json here send my data to an external server?

No. Both the validator and generator run 100% locally in your browser with zero external API calls.

Next step: see whether AI search recommends your brand

Protocol files make you agent-ready. CiteRank tests whether AI recommends you.

Run a focused check across ChatGPT, Gemini, Perplexity, Claude, Grok, and DeepSeek to see competitor mentions, cited sources, and the first page gap to fix.