poppy.json, field by field.
One JSON file on your domain is how a personal AI agent learns that your company exists, what it may do there and how its person signs in. This is every field in Version 1.0, read against the file Stacktree serves in production, with the checks an agent runs before it trusts yours.
The Poppy Simulator tests any domain. Free, no sign-up.
What is poppy.json?
poppy.json is the discovery file of the Personal Agent Protocol (Poppy). A company publishes it at /.well-known/poppy.json on its own domain, over HTTPS. It tells a person's AI agent which protocol version the company speaks, who the company is, how sign-in works, and which APIs, website access or support agent it offers. Version 1.0 requires three things in it: a version, the organization, and at least one channel.
A real file
This is what stacktr.ee/.well-known/poppy.json served on 14 November 2026, the day Version 1.0 was published. The four descriptions are shortened here. Everything else is as served.
{
"protocol_version": "1.0",
"supported_versions": {
"0.4": "https://stacktr.ee/.well-known/poppy/0.4.json",
"0.3": "https://stacktr.ee/.well-known/poppy/0.3.json"
},
"organization": {
"name": "Stacktree",
"domain": "stacktr.ee",
"logo_uri": "https://stacktr.ee/favicon.svg"
},
"auth": {
"issuer": "https://api.stacktr.ee",
"scopes": {
"sites:read": "See the pages in their Stacktree account ... Not needed to publish.",
"sites:write": "Publish pages into their Stacktree account ... Not needed for a one-off page."
},
"scope_hints": {
"sites:read": { "changes": "none", "personal_data": true },
"sites:write": { "changes": "irreversible", "personal_data": true }
}
},
"apis": [
{ "type": "mcp", "url": "https://api.stacktr.ee/mcp", "description": "Publish a page to a private link ..." },
{ "type": "openapi", "url": "https://api.stacktr.ee/openapi.json", "description": "The same over REST ..." }
],
"tasks": {
"endpoint": "https://api.stacktr.ee/poppy/tasks"
}
} Read top to bottom, it says: we follow 1.0 and still serve two drafts. We are Stacktree at stacktr.ee. A person can sign in through one OAuth server, and there are two things they can approve. You can reach us through an MCP server or a REST API. And there is an address to ask what we chose not to offer.
The smallest valid file
A company that only wants agents to use one API signed out needs this much:
{
"protocol_version": "1.0",
"organization": { "name": "Example Company", "domain": "example.com" },
"apis": [
{ "type": "openapi", "url": "https://api.example.com/openapi.json", "description": "Track an order" }
]
} No OAuth, no scopes, no agent of your own. That is a complete Version 1.0 document.
Every field
From section 3.1 of the 1.0 spec. Required fields first.
protocol_version(required). The version this file follows, asmajor.minor. An agent uses the file only if it implements a compatible version. From 1.0, a newer minor version does not break older agents, which ignore fields they do not know.organization(required). A displayname, thedomain, and an optionallogo_uri. The domain must be the host that serves the file, after any redirects. The name is only a label: the domain is the identity.- One of
apis,weboragent(required). The three channels. A file with none of them offers an agent nothing to do. apis. A list. Each entry has atypesuch asopenapiormcp, aurl, and a shortdescriptionthat helps the agent pick the right one. Write the description for a model choosing between entries, not for a person browsing docs.web. Your website. An optionalbrowser_session_endpointis where the agent's browser joins its Session, so it can browse signed in.web.disabled: trueasks agents not to use a browser on your site at all.web.unscoped: truewarns that the website does not apply your other scopes.agent. Your own Company Agent, if you have one.protocolslists each conversation endpoint with atype, anendpointand, required since 1.0, adescriptionof what the agent there can help with.supported_versions. The other versions you serve, each mapped to the address of that version's own document. This is how a company moves to a new version without cutting off agents on the old one.auth. Sign-in details. Leave it out entirely if agents only use you signed out.auth.issuer. Your OAuth issuer. Required only when your domain's protected resource metadata lists more than one authorization server. With one server you may leave it out.auth.disabled.trueif you have an issuer but offer personal agents no sign-in.auth.scopes. A description for each scope, keyed by scope name. You choose the names. Say what the scope allows, when an agent should ask for it, and whether the task can be done without it. Agents show this to the person, and use it to avoid asking for sign-in they do not need.auth.scope_hints. Two hints per scope:changes(none,reversibleorirreversible) andpersonal_data. An agent can use them to decide how carefully to confirm with its person first.tasks. Oneendpoint. For a given Session it returns the tasks you chose not to offer, any skills you publish, and where to send feedback.extensions. The extensions you support, by name and version, such as the UCP extension for checkout.
What an agent checks before trusting it
A file that parses is not yet a file an agent will use. Section 3 has the agent verify:
- The address. The final URL, after redirects, has the path
/.well-known/poppy.jsonexactly, with no query, and every hop was HTTPS. - The domain.
organization.domainequals the host that served the file. A copy of your file on someone else's domain fails here. - The issuer, if there is one. The agent finds your OAuth server from
/.well-known/oauth-protected-resourceon your domain, then confirms that server's own metadata listshttps://yourdomainunderprotected_resources. Both sides have to point at each other. - The version. It reads
protocol_versionandsupported_versionsand takes the newest one it implements. - Every URL is HTTPS, and none points at a private or loopback address.
Mistakes that break it
The first three are our own. The rest follow from the checks above.
- Metadata that names the wrong resource. Until 6 November, the protected resource document at the root of our API host gave our MCP server's address as its
resource, because that is where the MCP server sent clients. Under RFC 9728 the document at a host's root has to name that host. An agent that asks about one resource and is told about another should refuse the answer, and nothing in your own logs says why it left. - Stopping at a version you do not know. This one is for agent builders. Our simulator read
"protocol_version": "1.0", did not recognize it, and gave up before readingsupported_versions, where a version it did speak was listed. Read the links first. - Scope descriptions that only say what a scope is. "Read access" tells an agent nothing about whether to ask for it. Ours now say when the scope is needed and when it is not, because our main action, publishing a page, needs no sign-in at all.
- An issuer that does not point back. Your domain names your OAuth server, but the server's metadata does not list your domain under
protected_resources. A careful agent stops there. - Serving the file from the API host only. The file speaks for the host that serves it. If your product lives at
example.comand the file is only onapi.example.com, agents looking forexample.comfind nothing. - Vague API descriptions. With two APIs listed, the description is all an agent has to choose between them. Name the tasks.
- Leaving an old document unreachable. If you list a version under
supported_versions, its document has to answer. Agents on that version read it directly.
Fields from the drafts that are gone
Many examples online were written against the October drafts. If you copied one, check for these:
poppy_domains. Gone. The domain and its sign-in server now prove their link through OAuth metadata, as above.- Sign-in types in
poppy.json. Since 0.3, whether you offer Direct or Device Sign-In is read from your OAuth server's metadata. poppy:readandpoppy:write. Since 0.3, scopes are your own names, described underauth.scopes.feedback.endpoint. Moved in 0.4. An agent reads the feedback address from the document attasks.endpoint.
Test yours
Start with one request:
curl -sL https://yourdomain/.well-known/poppy.json Then let an agent read it. Open the Poppy Simulator, choose Test a company and enter your domain. It runs the checks above, starts a signed-out Session, tries the first API you list, and sends the requests a company must refuse. Each result names the spec section it tested. The build log explains what it does and what it found in ours.
For the rest of the protocol, from Sessions to sign-in, see the Personal Agent Protocol, explained.
Frequent questions
What is poppy.json? +
Where does poppy.json go? +
Which fields are required in poppy.json? +
How do I check that my poppy.json is valid? +
Does poppy.json need an OAuth server? +
What happened to poppy_domains and feedback.endpoint? +
Can one poppy.json serve several protocol versions? +
Related guides
- How to implement it as a company What to build after the file: Sessions, agent identity, sign-in and testing, in order.
- Who supports Poppy Real poppy.json files from other companies, with the version each serves.
- Personal Agent Protocol 1.0, explained The whole protocol step by step, what 1.0 changed, and what it took to run it.
- Poppy Simulator A hosted test agent you can point at any domain that serves a poppy.json.
- Stacktree for AI agents What our own poppy.json leads to: publishing a page with or without an account.
- MCP spec changes in 2026 One of the API types a poppy.json can list.
Sources and further reading
- Personal Agent Protocol 1.0: Discovery ↗ Section 3 of the spec: where the file goes, what it speaks for and the field table.
- Personal Agent Protocol changelog ↗ When each field arrived, moved or was removed.
- RFC 9728: OAuth 2.0 Protected Resource Metadata ↗ How an agent finds your sign-in server from your domain.
- RFC 8414: OAuth 2.0 Authorization Server Metadata ↗ The server metadata that has to list your domain back.
- RFC 8615: Well-Known URIs ↗ Why the file lives under /.well-known/.
- Stacktree's live poppy.json ↗ The file the example on this page is taken from.
The file is the easy part.
Stacktree is a company agents can use today: an agent publishes a private page for its person with no account, over the Personal Agent Protocol, MCP or one HTTP request. Free to start, no card.
Sign up free →