# How to implement the Personal Agent Protocol as a company, in the order we would do it again · Stacktree

Source: https://stacktr.ee/implement-personal-agent-protocol

[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 15, 2026          Personal Agent Protocol · for companies

#  How to implement the Personal Agent Protocol.

   The spec is long, and you do not have to build it in the order it is written. Stacktree has run every version in production since the first draft. This is the order we would build in again, what each stage is for, what it cost, and where we got it wrong.

  [ Test your domain ](https://poppy-simulator.stacktr.ee)    [ Start with poppy.json ](/poppy-json)  The Poppy Simulator checks any company. Free, no sign-up.

##  How do you implement the Personal Agent Protocol?

Start with one file. Publish `/.well-known/poppy.json` on your main domain with your name, your domain and one channel, and personal agents can use you signed out. Then add in this order, stopping when your tasks are covered: accept and verify the `Poppy-Session` header, verify agents from their metadata documents, add OAuth sign-in with a consent page, decide on Device Sign-In, and serve more than one version. Test against an agent you did not write before you call it done.

## On this page

  -   01  [ Before you start: choose the tasks ](#tasks)
-   02  [ Stage 1: one file, signed out ](#file)
-   03  [ Stage 2: the Session header ](#session)
-   04  [ Stage 3: who is this agent? ](#identity)
-   05  [ Stage 4: sign-in and the consent page ](#oauth)
-   06  [ Stage 5: Device Sign-In, or not ](#device)
-   07  [ Stage 6: more than one version ](#versions)
-   08  [ Stage 7: test with an agent you did not write ](#test)
-   09  [ The official kit ](#kit)
-   10  [ What we would do differently ](#again)

## Before you start: choose the tasks

 The [adoption guide](https://personalagentprotocol.org/docs/1.0/guides#company-adoption) opens with the right advice: start with the tasks you want agents to do and the interfaces you already have. Write the tasks down and mark each one needs the account or does not. That one column decides how much of the protocol you build.

 For us the list was short. Publishing a page to a private link needs no account, and it is most of what people use Stacktree for. Seeing who opened a page, or changing a page later, needs the account. So the signed-out stages carried real value on their own, and we shipped them first.

## Stage 1: one file, signed out

 This is a complete Version 1.0 document:

```
`{
  "protocol_version": "1.0",
  "organization": { "name": "Example", "domain": "example.com" },
  "apis": [
    {
      "type": "openapi",
      "url": "https://api.example.com/openapi.json",
      "description": "Search the catalog and check stock. No account needed."
    }
  ]
}`
```

 Serve it at `https://example.com/.well-known/poppy.json`, on the domain your customers know, not only on your API host. If you have no OAuth for agents yet, return 404 from `/.well-known/oauth-protected-resource` on that domain and leave `auth` out. Check both:

```
`curl -s https://example.com/.well-known/poppy.json
curl -s -o /dev/null -w '%{http_code}\n' \
  https://example.com/.well-known/oauth-protected-resource`
```

 You need at least one of three channels. `apis` lists an OpenAPI description or an MCP server. `agent` lists your own support agent. `web` is your website, and it can be the whole file: Clerk's own `poppy.json` is 88 bytes and offers only `web`. Our [field guide](/poppy-json) covers every field.

 Cost: the smallest stage by far. Most of the time goes on writing descriptions an agent can choose from.

## Stage 2: the Session header

 Every request a personal agent sends to your APIs carries `Poppy-Session`, a short-lived token the agent signs for that one request, and `Poppy-Version`. Two rules (section 5.3):

  - Always accept it. Your gateway or firewall must not reject the headers.
 - Verify it before you rely on it. A stateless catalog endpoint can ignore the header. Anything you keep for a Session, such as a cart, a conversation or a draft, needs the full check first.
  Do the check in one place. Ours is one middleware in front of the REST API, the MCP server and the feedback endpoint, and it passes the verified agent, Session and User ID to whatever is behind it. What it checks: the signature, the audience, that the request's method and address match the ones signed, a 60-second freshness window, and that the token's id has not been seen before. Cache the agent's delegation, keyed by a hash of the whole thing, and most requests cost one signature check.

 What you get: a stable, pseudonymous User ID for each person, different at every company. You can recognize a returning person, rate-limit one agent, and keep state for someone who never signed in.

 Cost: moderate. Every check has to refuse the right things, and that takes longer than accepting the right ones.

## Stage 3: who is this agent?

 An agent's `client_id` is an HTTPS address where it publishes its name and public keys (4.1). There is no registration. To trust a signature you fetch that document, so:

  - Fetch it without following redirects, and check that the client_id inside equals the address you fetched.
 - Refuse private and loopback addresses. You are fetching an address a stranger gave you.
 - Cache the document and the keys, and rate-limit new client_id values.
 - Keep an allowlist or a blocklist. Accepting any agent is a choice, not a requirement.
 - Accept PS384 as well as ES256. Version 1.0 made it required.
  If your identity provider does not support clients identified by a metadata URL, the guides allow registering the agents you accept by their address and refusing the rest.

## Stage 4: sign-in and the consent page

 This is standard OAuth with a short list of Poppy's own choices (4.8). In the order they tend to fail:

  - Metadata that points both ways. Your domain's protected resource metadata names your authorization server, and that server's metadata lists https://yourdomain under protected_resources. The guides warn that this second field is the one an existing issuer is most likely to lack, and adding it may need a release from your vendor. Check it before you plan anything else.
 - Your own scope names. There are no poppy: scopes for your API. Use the scopes your API already has, and describe each in auth.scopes by what it allows and when an agent should ask. Ours are the same two our MCP connectors use.
 - Direct Sign-In. Authorization code with PKCE, S256 only. Match redirect_uri exactly. Return iss on every redirect, errors included: we missed it on two error paths and agents are told to reject a redirect without it.
 - The consent page. Name the agent and show the domain of its client_id, because the agent picks its own name and the domain is the part a person can trust. Say "connect", not "sign in with". Tell the person to continue only if they just asked that agent to do this. List every scope in plain words, every time: since 1.0 the agent sends prompt=consent, and you must not skip the page for scopes granted before.
 - Tokens. Ours: refresh tokens that last 90 days, Bearer access tokens that last an hour, and a token asked for with a resource works only at that resource. DPoP is optional in 1.0.
 - Sign-out. Revoke the agent's refresh tokens, and let a person disconnect an agent from their account settings. The Session carries on signed out.
  Decide now what no agent may ever reach. Ours is billing, API keys and the list of connected agents: those return `403 owner_only` whatever the scopes.

 Cost: the most of any stage. We had a first version live in two days on an OAuth server we already ran, and spent the next four weeks correcting it. Do not start here.

## Stage 5: Device Sign-In, or not

 Device Sign-In is for agents that cannot receive a browser redirect: glasses, a speaker, a phone call. The agent shows a link and a short code, and the person approves on any device. It is also easier to use for phishing, since anyone can start a request and send someone the link. The spec requires you to follow RFC 10027's best practices, which means a written risk assessment, and the guides say a company with high-value accounts, such as a bank, may offer Direct Sign-In only.

 If you offer it: codes that last about 10 minutes, a verification page on your own domain or your issuer's, opening the link must approve nothing, ask the person to confirm the code matches, and show the consent page every time. We wrote the assessment, and its main result was the owner-only list above. [Device Sign-In, explained](/device-sign-in) has the requests, the risk and what our assessment found.

## Stage 6: more than one version

 Agents do not all upgrade on the day you do. Publish each version's document at its own address, accept each by its `Poppy-Version` header, and list the older ones under `supported_versions`. Static files are enough.

 We learned this the hard way. Moving from 0.2 to 0.3 we had no way to serve both, so we switched, and every agent on 0.2 was cut off that day. Since 0.4 we run versions side by side: today 1.0, 0.4 and 0.3 all answer. If you start on 1.0 you start with the compatibility rule already in force, and this stage is mostly one check on one header.

## Stage 7: test with an agent you did not write

 Our tests were written from our own reading of the spec, so they could only confirm that reading. We learned more from a test agent built from the spec text alone and pointed at the live site. Three ways to get the same effect:

  - The official validator, part of the kit below. It runs as a test personal agent and each check names the requirement it tests.
 - [The Poppy Simulator](https://poppy-simulator.stacktr.ee). Choose Test a company and enter a domain. It runs discovery, a signed-out Session, your APIs and both kinds of sign-in, then sends requests a company must refuse and checks that you refuse them. Every request and response is shown. [How we built it and what it found](/blog/poppy-simulator).
 - A real agent. Sierra says Meta's Muse looks for poppy.json first on every site it visits. Watch your logs for the first Session that is not yours.
  Then file an implementation report in [the protocol's repository](https://github.com/personal-agent-protocol/personal-agent-protocol). The maintainers read them: they went through our first report point by point against the next version's text.

## The official kit

 The protocol ships a [Company implementation kit](https://personalagentprotocol.org/kit/company) for 1.0. It has two parts: a skill that a coding agent follows, and a validator.

```
`# Claude Code
/plugin marketplace add personal-agent-protocol/personal-agent-protocol
/plugin install personal-agent-protocol@personal-agent-protocol

# Other coding agents
npx skills add personal-agent-protocol/personal-agent-protocol \
  --skill implement-personal-agent-protocol`
```

 The skill works in five steps: survey your code and your live site (GET requests only), write a design for you to approve, build in milestones, verify against your deployment, and draft an implementation report. The milestones are Foundation, Interfaces, Sign-in and, optionally, Extensions. The validator needs Node 22.18 or later, a deployment it can reach over HTTPS, and an HTTPS address you control for the test agent's public files. Some requirements cannot be tested by a tool, such as consent wording and logging, and the kit lists those for you to review by hand.

 We did not use the kit for our own build, so we cannot tell you how well it works. Its milestones run in the same order as this page: the file and Sessions, then interfaces, then sign-in.

## What we would do differently

  - Ship signed-out first, and sooner. It is a fraction of the work, and it is the part agents can use without anyone approving anything.
 - Check the metadata before writing code. Our worst fault was one field in a document we had not thought about: the protected resource metadata at the root of our API host named our MCP server instead of the host. A personal agent that took it literally would have asked for the wrong token.
 - Build the outside test agent first. Ours came a week after we went live. It should have come before.
 - Plan for versions from the first day. Cutting off agents on an old version is avoidable, and we did it once.
 - Protect what you already have. Our authorization server also signs in Claude and ChatGPT connectors. We keep a test that runs their sign-in with every Poppy change switched on. [More on running both](/personal-agent-protocol-vs-mcp).
  The full write-ups are public: [Draft 0.1](https://github.com/personal-agent-protocol/personal-agent-protocol/issues/12), [Version 0.3](https://github.com/personal-agent-protocol/personal-agent-protocol/issues/75) and [Version 1.0](https://github.com/personal-agent-protocol/personal-agent-protocol/issues/93).

FAQ

## Frequent questions

     How long does it take to implement the Personal Agent Protocol? +  The signed-out start is one static file and can ship the day you write it. Account access is the expensive part: agent identity, a consent page and the token rules. We had a first version live two days after the first draft, on an OAuth server we already ran, and spent the next four weeks correcting it.   What is the minimum a company has to do? +  Publish /.well-known/poppy.json with protocol_version, your organization name and domain, and at least one of apis, web or agent. A company that offers only its website can stop there, with no auth section. Clerk's own file is 88 bytes and lists only web.   Do I need to build an OAuth server? +  Only for account access, and usually you extend the one you have. It must accept agents identified by a metadata URL instead of a registered client, list your domain under protected_resources in its metadata, and show a consent page. Check protected_resources first: the guides call it the field an existing issuer is most likely to be missing.   Is there an official tool to help? +  Yes. The Company implementation kit at personalagentprotocol.org/kit/company is a skill for coding agents plus a validator. The skill surveys your systems, writes a design for you to approve and builds in milestones. The validator acts as a test personal agent against your deployment. It needs Node 22.18 or later.   How do I test a Personal Agent Protocol implementation? +  With an agent you did not write. Your own tests encode your own reading of the spec. Use the official kit's validator, or the Poppy Simulator, which takes any domain, runs discovery, a signed-out Session, your APIs and sign-in, then sends requests you must refuse and checks that you do.   Do I have to verify the Poppy-Session header on every request? +  You must accept it everywhere, and verify it before you rely on anything it says. A stateless catalog endpoint can ignore it. An account endpoint can rely on the access token alone. Carts, conversations and anything else kept for a Session need the full check.   Should I offer Device Sign-In? +  Offer Direct Sign-In first. Device Sign-In suits agents with no browser, such as glasses or a phone call, but it is easier to use for phishing, and the spec requires a risk assessment under RFC 10027. A company whose accounts hold money or other high-value access may reasonably offer Direct Sign-In only.   What happens when the protocol changes? +  From 1.0, a newer 1.x version must not break a company built for an older one. To move, publish the new version's document, accept both by the Poppy-Version header, and list the old document under supported_versions. Our move from 0.4 to 1.0 was two code changes.
Keep reading

## Related guides

   -  [ poppy.json, field by field Every field in the file from Stage 1, with a live example and the mistakes that break it. ](/poppy-json)
-  [ The Personal Agent Protocol, explained What it is, how 1.0 works on the wire, and what changed from the drafts. ](/personal-agent-protocol)
-  [ Personal Agent Protocol vs MCP What each one does, and how one endpoint serves both. ](/personal-agent-protocol-vs-mcp)
-  [ Who supports Poppy The companies and agents we could verify, with the files they serve. ](/who-supports-poppy)

References

## Sources and further reading

   -  [ Personal Agent Protocol specification, Version 1.0 ↗ The requirements this page orders into stages. ](https://personalagentprotocol.org/docs/1.0/spec)
-  [ Personal Agent Protocol guides, for companies ↗ Recommended practice for each capability, from the maintainers. ](https://personalagentprotocol.org/docs/1.0/guides#companies)
-  [ Company implementation kit ↗ The official skill and validator for building the company side. ](https://personalagentprotocol.org/kit/company)
-  [ RFC 8628: OAuth 2.0 Device Authorization Grant ↗ The grant behind Device Sign-In. ](https://www.rfc-editor.org/rfc/rfc8628)
-  [ RFC 9728: OAuth 2.0 Protected Resource Metadata ↗ The document that links your domain to your sign-in server. ](https://www.rfc-editor.org/rfc/rfc9728)
-  [ Stacktree implementation report, Version 1.0 ↗ Our latest write-up for the maintainers, with what changed for us in 1.0. ](https://github.com/personal-agent-protocol/personal-agent-protocol/issues/93)

##  See a finished one first.

 Stacktree runs Version 1.0 in production. Read our poppy.json, or open the simulator and watch an agent discover us, start a Session and publish a page. Free, no sign-up.

 [ Sign up free → ](https://app.stacktr.ee/?join=1&from=cta_implement_personal_agent_protocol)       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
