{"slug": "what-is-poppy-json-the-well-known-file-that-tells-ai-agents-how-to-work-with", "title": "What Is poppy.json? The /.well-known File That Tells AI Agents How to Work With Your Company", "summary": "The Personal Agent Protocol project published Draft 0.1 of its specification on October 9, 2026, defining poppy.json, a JSON file companies host at https://{domain}/.well-known/poppy.json so AI agents can discover in one request how to work with them. The file carries a protocol_version, organization name and domain, an OAuth issuer under auth, and lists of agent, apis (openapi or mcp) and web interfaces, with optional extensions such as operations. The draft places the trust anchor in the company's OAuth server rather than the JSON file alone, requiring agents to fetch the file over HTTPS and verify that organization.domain matches the originally requested domain.", "body_md": "# What Is poppy.json? The /.well-known File That Tells AI Agents How to Work With Your Company\n\npoppy.json is the discovery file in the Personal Agent Protocol (Poppy): organization, OAuth issuer, MCP and OpenAPI APIs and extensions, with a worked example.\n\n`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](https://personalagentprotocol.org/docs/spec) was published on October 9, 2026, and the project calls the whole thing changeable, so treat the details below as a draft.\n\n## What the file is for\n\nBefore 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](https://contextiq.trango-compute.com/blog/what-is-personal-agent-protocol-pap-sierra-meta).\n\n## The fields\n\n| Field | Required? | What it holds | \n|---|---|---|\n| `protocol_version` | Yes | `\"major.minor\"` , for example`\"0.1\"` | \n| `organization` | Yes | `name` and`domain` ; the domain must match the host the file was fetched from (ignoring`www.` ) | \n| `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` | \n| `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` | \n| `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` | \n| `web` | One of the three is required | `browser_session_endpoint` : where an agent's browser joins a session | \n| `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` | \n\n## A worked example (fictional)\n\n**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.\n\n```\n{\n  \"protocol_version\": \"0.1\",\n  \"organization\": {\n    \"name\": \"Northwind Outfitters\",\n    \"domain\": \"northwind.example.test\"\n  },\n  \"auth\": {\n    \"issuer\": \"https://auth.northwind.example.test\",\n    \"direct\": { \"scopes\": [\"poppy:read\", \"poppy:write\"] },\n    \"device\": { \"scopes\": [\"poppy:read\"] }\n  },\n  \"apis\": [\n    {\n      \"type\": \"mcp\",\n      \"url\": \"https://mcp.northwind.example.test/mcp\",\n      \"description\": \"Order lookup and returns\"\n    },\n    {\n      \"type\": \"openapi\",\n      \"url\": \"https://api.northwind.example.test/openapi.json\",\n      \"description\": \"Product catalog and stock levels\"\n    }\n  ],\n  \"web\": {\n    \"browser_session_endpoint\": \"https://northwind.example.test/poppy/browser-session\"\n  },\n  \"extensions\": { \"operations\": { \"version\": 1 } }\n}\n```\n\nRead 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).\n\n## What an agent checks before trusting it\n\nThe draft puts the trust anchor in the OAuth server, not in the JSON file alone. Before using a `poppy.json`, an agent must:\n\n1. Fetch it over HTTPS. Redirects are allowed, but every destination must be HTTPS, and `organization.domain` must still match the domain originally requested.\n2. Fetch the company's OAuth Authorization Server Metadata (RFC 8414).\n3. Confirm the metadata's `issuer` exactly equals`auth.issuer` , and that its`poppy_domains` list includes`organization.domain` .\n\nThat 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`.\n\n## Common mistakes the rules imply\n\n- **Declaring `apis` or `agent` with no `auth` block.** The draft requires`auth` whenever those are present.\n- **A domain that does not match the host.**`organization.domain` must equal the host the file is served from.\n- **A redirect to plain HTTP.** Every redirect destination must be HTTPS.\n- **An issuer mismatch.**`auth.issuer` and the metadata's`issuer` must match exactly, including any trailing slash.\n- **No `poppy_domains` in the OAuth metadata.** Agents are required to look for it.\n- **Treating the file as the whole integration.** It only describes; sign-in, DPoP-bound tokens and the interfaces themselves are still yours to build.\n\n## How it relates to other discovery files\n\nSeveral 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](https://contextiq.trango-compute.com/blog/make-website-discoverable-ai-agents-llms-txt-agent-cards) covers the others. A company can publish several.\n\n## Where ContextIQ fits\n\nThe [Agent Protocol Inspector](https://contextiq.trango-compute.com/agent-readiness-detector) scans a URL for MCP servers, A2A agent cards and ARD catalogs. It does not read `poppy.json` today. If your `poppy.json` lists an MCP server, you can scan that server's URL to see what an agent would discover there. The [OIDC Inspector](https://contextiq.trango-compute.com/oidc-inspector) shows what your authorization server publishes, but it does not check PAP-specific fields such as `poppy_domains`.\n\n## Sources\n\nFollow Trango Compute on LinkedIn\n\nWe post updates on new tools, context engineering patterns, and LLM cost research.\n\n[Follow on LinkedIn](https://www.linkedin.com/company/trango-compute)", "url": "https://wpnews.pro/news/what-is-poppy-json-the-well-known-file-that-tells-ai-agents-how-to-work-with", "canonical_source": "https://contextiq.trango-compute.com/blog/what-is-poppy-json-well-known-file-ai-agents", "published_at": "2026-10-09 00:00:00+00:00", "updated_at": "2026-10-10 00:27:06.517906+00:00", "lang": "en", "topics": ["agent-protocols", "ai-agents", "ai-tools", "developer-tools"], "entities": ["Personal Agent Protocol", "Poppy", "Northwind Outfitters", "OpenAPI", "Model Context Protocol"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/what-is-poppy-json-the-well-known-file-that-tells-ai-agents-how-to-work-with", "markdown": "https://wpnews.pro/news/what-is-poppy-json-the-well-known-file-that-tells-ai-agents-how-to-work-with.md", "text": "https://wpnews.pro/news/what-is-poppy-json-the-well-known-file-that-tells-ai-agents-how-to-work-with.txt", "jsonld": "https://wpnews.pro/news/what-is-poppy-json-the-well-known-file-that-tells-ai-agents-how-to-work-with.jsonld"}}