# What is poppy.json?

poppy.json is a small JSON file a business publishes at yourdomain.com/.well-known/poppy.json. It tells a person's AI agent who the business is and how to work with it: which MCP server, API or company agent to use, whether the website may be used, and how customers sign in. It is the discovery file of the Personal Agent Protocol, Poppy for short.

|  |  |
| --- | --- |
| Where it lives | https://yourdomain.com/.well-known/poppy.json |
| Format | JSON |
| Specification | [Personal Agent Protocol 1.0](https://personalagentprotocol.org/docs/1.0/spec) |
| Published by | Sierra, with Meta and a group of design partners |
| Required | protocol_version, organization, and at least one of agent, apis or web |
| Cost | Free. Make one with the [poppy.json generator](https://getquotebee.com/tools/poppy-json-generator/) |

## How an AI agent uses poppy.json

- A person asks their agent to do something with a business: track an order, book a table, get a quote from a plumber.
- The agent fetches https://thebusiness.com/.well-known/poppy.json, following redirects.
- It checks that organization.domain matches the site that served the file. If not, it ignores the file.
- It picks a channel: the business's own agent (agent), its MCP server or API (apis), or the website (web).
- If the task needs the customer's account, it asks the customer to sign in and approve the scopes listed under auth.
- It does the task through that channel, and can send requests the business does not support yet to tasks.endpoint.

## A complete poppy.json

An online store with customer accounts, an API, and a website agents may use:

```
{
  "protocol_version": "1.0",
  "organization": {
    "name": "Example Outfitters",
    "domain": "exampleoutfitters.com",
    "logo_uri": "https://exampleoutfitters.com/logo.png"
  },
  "auth": {
    "scopes": {
      "orders:read": "See your orders and returns. Needed to track an order",
      "orders:write": "Return or exchange items. Needed for any change to an order"
    },
    "scope_hints": {
      "orders:read": {
        "changes": "none",
        "personal_data": true
      },
      "orders:write": {
        "changes": "irreversible",
        "personal_data": true
      }
    }
  },
  "apis": [
    {
      "type": "openapi",
      "url": "https://api.exampleoutfitters.com/openapi.json",
      "description": "Orders, returns and exchanges"
    }
  ],
  "web": {}
}
```

More, from a plumber with no API to a software company with an MCP server: [poppy.json examples](https://getquotebee.com/poppy-json/examples/).

## Every field

| Field | Required | What it says |
| --- | --- | --- |
| protocol_version | Yes | The version the file follows: "1.0". |
| organization | Yes | Your name, the domain that serves the file, and an optional https logo. |
| apis | One of apis, agent or web | Your MCP server or OpenAPI description: a type ("mcp" or "openapi"), an https URL and a short description. |
| agent | One of apis, agent or web | Your own company agent: the https endpoint where personal agents hold conversations with it. |
| web | One of apis, agent or web | Whether agents may browse your site, and where a browser joins a session. {} means browsing is fine. |
| auth | No | Sign in through OAuth, the scopes agents can ask for, and hints on whether each scope changes anything or touches personal data. Set disabled to true if you offer no sign in. |
| tasks | No | An https endpoint for tasks you do not support yet, and for feedback. |
| supported_versions | No | Other protocol versions you serve, each with the URL of its document. |
| extensions | No | The extensions you support, keyed by name. |

## Who is behind it

Sierra published the Personal Agent Protocol with Meta and a group of design partners, including OpenAI, Shopify and Stripe. Version 1.0 came out on November 13, 2026. Meta's Muse agent now looks for a poppy.json first on every site it visits, and Shopify and Wix publish one automatically for their sites. Most other websites, including almost every WordPress site, do not have one yet.

## poppy.json, MCP, llms.txt and robots.txt

| File | What it is for |
| --- | --- |
| poppy.json | How a customer's own agent can work with your business: which channels, and how customers sign in |
| An MCP server | The tools an agent can call, such as getting a price or booking. poppy.json can point to it |
| llms.txt | A plain text guide to your site's content for language models |
| robots.txt | Which crawlers may visit which pages |
| LocalBusiness structured data | Your business facts, such as address, hours and services, in a form search engines read |

## How to add poppy.json to your website

- Make the file: the [poppy.json generator](https://getquotebee.com/tools/poppy-json-generator/) writes it and checks it against the spec.
- Upload it so it is served at exactly /.well-known/poppy.json on your own domain, over https.
- Check the live file with the [poppy.json validator](https://getquotebee.com/tools/poppy-json-validator/).

WordPress sites can upload it with the host's file manager. Wix, Squarespace and Webflow do not allow files in /.well-known/, and need Cloudflare in front of the site. [Setup by platform](https://getquotebee.com/tools/poppy-json-generator/).

## For trades businesses

A plumber, roofer or mover does not need to build an agent to use Poppy. With Quotebee, your poppy.json points agents to a listing we run for you, with your services, area and prices, and quote requests come straight to you. [Get listed free](https://getquotebee.com/tools/poppy-json-generator/).

## Questions

### Is poppy.json required?

No. It is optional, like robots.txt. Without it, agents fall back to reading and using your website like a person would.

### Does poppy.json help my Google ranking?

No. Search engines do not use it for ranking. It is for agents acting for a customer.

### Do I need an API or MCP server to publish one?

No. The smallest valid file names your business and allows agents to use your website. You can add APIs or an agent later.

### Which agents read poppy.json today?

Support is just starting. The protocol's design partners include OpenAI, which is a reason to expect it in ChatGPT, but no agent has announced full support yet.

### Can the endpoints live on another domain?

Yes. The file must be on your own domain, but the MCP server, API or agent it points to can be hosted anywhere, which is how a service like Quotebee can answer for a business.

### What is the difference between poppy.json and agents.json?

agents.json is a separate, earlier proposal for describing APIs to agents. poppy.json is the discovery file of the Personal Agent Protocol and also covers sign in, company agents and website use.

## Sources

- [Personal Agent Protocol 1.0 specification](https://personalagentprotocol.org/docs/1.0/spec)
- [Sierra: Personal Agent Protocol announcement](https://sierra.ai/blog/poppy)

Updated Nov 17, 2026.

Run a trades business? Get quoted in ChatGPT. Add your prices and service area. When customers ask ChatGPT or Claude for your trade, they get your price and you get the request. Free to set up, about ten minutes. https://getquotebee.com/tools/poppy-json-generator/

Source: https://getquotebee.com/poppy-json/
