poppy.json is a small JSON file a company publishes at https://{domain}/.well-known/poppy.json so that a person's AI agent can find out, in one request, how the company wants agents to work with it. It is the discovery step of the Personal Agent Protocol (PAP, also called Poppy). The Draft 0.1 specification was published on October 9, 2026, and the project calls the whole thing changeable, so treat the details below as a draft.
What the file is for
Before an agent can sign in, call an API, browse a site or start a conversation, it has to know what exists. poppy.json answers four questions: who is this company, which OAuth server do I authenticate against, which interfaces are on offer (APIs, a website, a company agent), and which optional features does it support. For the bigger picture, see what PAP is.
The fields
| Field | Required? | What it holds |
|---|---|---|
protocol_version | Yes | "major.minor", for example "0.1" |
organization | Yes | name and domain; the domain must match the host the file was fetched from (ignoring www.) |
auth | Required if agent, apis or web.browser_session_endpoint is present | issuer (an HTTPS URL for the OAuth server), plus optional direct, device and mediated sign-in blocks with their scopes, and custom_scopes |
agent | One of agent, apis, web is required | protocols: a list of objects with a type (such as "poppy"), an HTTPS endpoint for conversations, and an optional resource |
apis | One of the three is required | A list; each item has a type ("openapi" or "mcp"), a url, a short description, and an optional resource |
web | One of the three is required | browser_session_endpoint: where an agent's browser joins a session |
extensions | No | Optional features, each with a version; the built-in one is operations, and third-party ones use domain-prefixed names such as example.com/gift-wrap |
A worked example (fictional)
Illustrative. Northwind Outfitters is a made-up company, and these URLs do not exist. The shape follows the Draft 0.1 field list above; the spec text is the authority on exact values.
{
"protocol_version": "0.1",
"organization": {
"name": "Northwind Outfitters",
"domain": "northwind.example.test"
},
"auth": {
"issuer": "https://auth.northwind.example.test",
"direct": { "scopes": ["poppy:read", "poppy:write"] },
"device": { "scopes": ["poppy:read"] }
},
"apis": [
{
"type": "mcp",
"url": "https://mcp.northwind.example.test/mcp",
"description": "Order lookup and returns"
},
{
"type": "openapi",
"url": "https://api.northwind.example.test/openapi.json",
"description": "Product catalog and stock levels"
}
],
"web": {
"browser_session_endpoint": "https://northwind.example.test/poppy/browser-session"
},
"extensions": { "operations": { "version": 1 } }
}Read it as a menu. An agent that only needs stock levels can use the OpenAPI description. One that needs to look up an order can use the MCP server. Both authenticate against the single issuer in auth, and a customer can sign in directly in a browser (read and write) or on another device (read only).
What an agent checks before trusting it
The draft puts the trust anchor in the OAuth server, not in the JSON file alone. Before using a poppy.json, an agent must:
- Fetch it over HTTPS. Redirects are allowed, but every destination must be HTTPS, and
organization.domainmust still match the domain originally requested. - Fetch the company's OAuth Authorization Server Metadata (RFC 8414).
- Confirm the metadata's
issuerexactly equalsauth.issuer, and that itspoppy_domainslist includesorganization.domain.
That last check ties a domain to an issuer from both sides, which is meant to stop one company's file from pointing agents at another company's login. It also means publishing poppy.json is not enough: your authorization server metadata has to carry poppy_domains.
Common mistakes the rules imply
- Declaring
apisoragentwith noauthblock. The draft requiresauthwhenever those are present. - A domain that does not match the host.
organization.domainmust equal the host the file is served from. - A redirect to plain HTTP. Every redirect destination must be HTTPS.
- An issuer mismatch.
auth.issuerand the metadata'sissuermust match exactly, including any trailing slash. - No
poppy_domainsin the OAuth metadata. Agents are required to look for it. - Treating the file as the whole integration. It only describes; sign-in, DPoP-bound tokens and the interfaces themselves are still yours to build.
How it relates to other discovery files
Several well-known files now exist for agents, and they answer different questions. poppy.json describes how a person's agent should authenticate and which interfaces a company offers under PAP. An agent-card.json describes an A2A agent's identity and skills. llms.txt is a plain-text guide for language models. Our overview of making a website discoverable to AI agents covers the others. A company can publish several.
Where ContextIQ fits
The Agent Protocol Inspector fetches /.well-known/poppy.json, lints it against the Draft 0.1 rules above, and runs the issuer cross-check: it fetches the authorization server metadata at auth.issuer and reports whether the issuer matches exactly, whether poppy_domains lists your domain, and whether the endpoints your sign-in methods need are present. It reads published documents only. It does not sign in, test DPoP, or call the APIs and conversation endpoint your file lists, and it is not a conformance test. The spec is a draft, so its rules may change. If your file lists an MCP server, you can scan that server's URL in the same tool to see what an agent would discover there. The OIDC Inspector shows what your authorization server publishes in general.