# poppy.json: every field in Personal Agent Protocol 1.0, with a live example · Stacktree

Source: https://stacktr.ee/poppy-json

[Skip to content](#main) PFrom Product Hunt? Your first pages are free, no card. Code `PRODUCTHUNT` takes 50% off your first month of Studio.[Start free &rarr;](https://app.stacktr.ee/?join=1&from=producthunt)

&times;   A Stacktree customer sent you. Your first month is 50% off on any plan, taken off at checkout. [Start free &rarr;](https://app.stacktr.ee/?join=1&from=referral)

 &times;    [Stacktree](/)[Developers](/developers)[Agents](/agents)[Docs](/docs)[Use cases](/use-cases)[Pricing](/pricing)[Blog](/blog)[Dashboard](https://app.stacktr.ee)[Sign in →](https://app.stacktr.ee)      By [ Steve Smith ](/about) · Founder, Stacktree  ·  Last updated November 14, 2026          Personal Agent Protocol · discovery

#  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.

  [ Check a poppy.json ](https://poppy-simulator.stacktr.ee)    [ The protocol, explained ](/personal-agent-protocol)  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.

## On this page

  -   01  [ A real file ](#example)
-   02  [ The smallest valid file ](#minimal)
-   03  [ Every field ](#fields)
-   04  [ What an agent checks before trusting it ](#checks)
-   05  [ Mistakes that break it ](#mistakes)
-   06  [ Fields from the drafts that are gone ](#gone)
-   07  [ Test yours ](#test)

## A real file

 This is what [stacktr.ee/.well-known/poppy.json](https://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](https://personalagentprotocol.org/docs/1.0/spec). Required fields first.

  - protocol_version (required). The version this file follows, as major.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 display name, the domain, and an optional logo_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, web or agent (required). The three channels. A file with none of them offers an agent nothing to do.
 - apis. A list. Each entry has a type such as openapi or mcp, a url, and a short description that 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 optional browser_session_endpoint is where the agent's browser joins its Session, so it can browse signed in. web.disabled: true asks agents not to use a browser on your site at all. web.unscoped: true warns that the website does not apply your other scopes.
 - agent. Your own Company Agent, if you have one. protocols lists each conversation endpoint with a type, an endpoint and, required since 1.0, a description of 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. true if 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, reversible or irreversible) and personal_data. An agent can use them to decide how carefully to confirm with its person first.
 - tasks. One endpoint. 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.json exactly, with no query, and every hop was HTTPS.
 - The domain. organization.domain equals 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-resource on your domain, then confirms that server's own metadata lists https://yourdomain under protected_resources. Both sides have to point at each other.
 - The version. It reads protocol_version and supported_versions and 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 reading supported_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.com and the file is only on api.example.com, agents looking for example.com find 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:read and poppy:write. Since 0.3, scopes are your own names, described under auth.scopes.
 - feedback.endpoint. Moved in 0.4. An agent reads the feedback address from the document at tasks.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](https://poppy-simulator.stacktr.ee), 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](/blog/poppy-simulator) 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](/personal-agent-protocol).

FAQ

## Frequent questions

     What is poppy.json? +  poppy.json is the discovery file of the Personal Agent Protocol. 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.   Where does poppy.json go? +  At https://yourdomain/.well-known/poppy.json, exactly. The address may redirect, for example from www to the bare domain, but the final address must end in that same path with no query string. An agent ignores a file served from any other path, so an upload folder cannot speak for your domain.   Which fields are required in poppy.json? +  In Version 1.0, protocol_version and organization (with a name and a domain) are required, plus at least one of three channels: apis, web or agent. Everything else is optional, including auth. A company that serves agents signed out needs no sign-in details at all.   How do I check that my poppy.json is valid? +  Fetch it with curl and confirm it returns JSON over HTTPS with your own domain in organization.domain. Then point a real agent at it: the Poppy Simulator reads the file, runs the checks the spec asks of an agent, starts a signed-out Session and shows each request with the rule it tested.   Does poppy.json need an OAuth server? +  No. The auth section is optional. Without it, agents use the company signed out. When a company does offer sign-in, the agent finds the OAuth server from the domain's protected resource metadata, and auth.issuer is only required when that metadata lists more than one server.   What happened to poppy_domains and feedback.endpoint? +  Both were fields in the October drafts and are gone. The link between a domain and its sign-in server is now proven with standard OAuth metadata instead of poppy_domains. The feedback address moved in 0.4: an agent reads it from the document at tasks.endpoint, per Session.   Can one poppy.json serve several protocol versions? +  Yes. protocol_version names the version the file follows, and supported_versions maps each other version you serve to the address of that version's own document. An agent picks the newest version it implements. From 1.0, any 1.x agent can use a 1.0 document.
Keep reading

## Related guides

   -  [ How to implement it as a company What to build after the file: Sessions, agent identity, sign-in and testing, in order. ](/implement-personal-agent-protocol)
-  [ Who supports Poppy Real poppy.json files from other companies, with the version each serves. ](/who-supports-poppy)
-  [ Personal Agent Protocol 1.0, explained The whole protocol step by step, what 1.0 changed, and what it took to run it. ](/personal-agent-protocol)
-  [ Poppy Simulator A hosted test agent you can point at any domain that serves a poppy.json. ](/blog/poppy-simulator)
-  [ Stacktree for AI agents What our own poppy.json leads to: publishing a page with or without an account. ](/agents)
-  [ MCP spec changes in 2026 One of the API types a poppy.json can list. ](/blog/mcp-2026-spec-changes)

References

## 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. ](https://personalagentprotocol.org/docs/1.0/spec#discovery)
-  [ Personal Agent Protocol changelog ↗ When each field arrived, moved or was removed. ](https://personalagentprotocol.org/docs/changelog)
-  [ RFC 9728: OAuth 2.0 Protected Resource Metadata ↗ How an agent finds your sign-in server from your domain. ](https://www.rfc-editor.org/rfc/rfc9728)
-  [ RFC 8414: OAuth 2.0 Authorization Server Metadata ↗ The server metadata that has to list your domain back. ](https://www.rfc-editor.org/rfc/rfc8414)
-  [ RFC 8615: Well-Known URIs ↗ Why the file lives under /.well-known/. ](https://www.rfc-editor.org/rfc/rfc8615)
-  [ Stacktree's live poppy.json ↗ The file the example on this page is taken from. ](https://stacktr.ee/.well-known/poppy.json)

##  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 → ](https://app.stacktr.ee/?join=1&from=cta_poppy_json)       Private hosting for the HTML your agents make.

[](https://betalist.com/startups/stacktree?utm_campaign=badge-stacktree&utm_medium=badge&utm_source=badge-featured)[Featured on](https://devhunt.org/tool/stacktree)[](https://buildlist.io)[Get started free](https://app.stacktr.ee/?join=1)

## Product

- [Page video](/page-video)
- [Ask this page](/ask-this-page)
- [Client spaces](/client-spaces)
- [Templates](/templates)
- [Example deliverables](/examples)
- [Custom domains](/custom-domains)
- [Client feedback](/client-feedback-loop)
- [One-time links](/one-time-view-links)
- [See how pages get read](/page-engagement)
- [Made with Stacktree](/made-with)
- [Security](/security)
- [Watch the demo](/demo)

## Agents

- [All integrations](/agents)
- [Claude Code](/claude-code)
- [OpenAI Codex](/codex)
- [Cursor](/cursor)
- [Claude.ai connector](/claude-ai-connector)
- [Claude Cowork](/what-is-claude-cowork)
- [Meta Muse](/muse)
- [MCP server](/mcp-publish-html)
- [Deploy from Claude Code](/deploy-html-from-claude-code)
- [Skills](/skills)
- [Slack app](/slack)
- [n8n node](/n8n)
- [Agent payments (x402)](/x402)

## Alternatives

- [All comparisons](/alternatives)
- [Head-to-head comparisons](/compare)
- [Tiiny Host](/tiiny-host-alternative)
- [GitHub Pages (private)](/github-pages-private-alternative)
- [Vercel](/vercel-alternative-for-agents)
- [ngrok](/ngrok-alternative-for-html)
- [Display.dev](/display-dev-alternative)
- [Static.app](/static-app-alternative)
- [OpenAI Codex Sites](/openai-codex-sites-alternative)
- [here.now](/here-now-alternative)
- [Shippage](/shippage-ai-alternative)
- [Best private hosting](/best-private-html-hosting)

## Use cases

- [All use cases](/use-cases)
- [Share with clients](/share-with-clients)
- [Send a file to a client](/share-html-file-with-client)
- [Share Claude artifacts](/share-claude-artifacts)
- [Share Jupyter notebooks](/share-jupyter-notebook-html)
- [Host Storybook privately](/host-storybook-privately)
- [Architecture diagrams](/share-architecture-diagrams)
- [AI-generated reports](/host-ai-reports)
- [Internal HTML tools](/internal-tool-hosting)
- [Private HTML hosting](/private-html-hosting)
- [Vibe-coded page hosting](/vibe-coding-hosting)
- [Leave a website builder](/website-builder-migration)

## Learn

- [Blog](/blog)
- [Glossary](/glossary)
- [FAQ](/faq)
- [Where AI output should live](/where-ai-output-lives)
- [Agent-loop hosting](/agent-loop-hosting)
- [Why agents need a publish primitive](/blog/why-agents-need-a-publish-primitive)
- [MCP servers explained](/blog/mcp-servers-explained-for-developers)
- [What changed in the 2026-07 MCP spec](/blog/mcp-2026-spec-changes)
- [Sites in Codex explained](/blog/sites-in-codex-explained)
- [Private-by-default hosting](/blog/private-by-default-html-hosting)
- [An agent paid us $1 (x402)](/blog/agent-paid-to-provision-itself)
- [When a loop hits a paywall](/blog/loop-engineering-paywall)
- [Pricing](/pricing)
- [Self-host (new)](/self-host)
- [Changelog](/changelog)
- [Docs](https://stacktr.ee/docs)
- [About](/about)
© 2026 Stacktree · stacktr.ee

[Privacy](/privacy)[Terms](/terms)[Security](/security)[Dashboard](https://app.stacktr.ee)[npm](https://www.npmjs.com/package/stacktree-mcp)[Sitemap](/sitemap.xml)[llms.txt](/llms.txt)[API spec](/openapi.json)

---
Full markdown summary of the Stacktree marketing surface: https://stacktr.ee/llms-full.txt
