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.
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.
Before you start: choose the tasks
The adoption guide 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 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_idinside 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_idvalues. - 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://yourdomainunderprotected_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 inauth.scopesby 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,
S256only. Matchredirect_uriexactly. Returnisson 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 sendsprompt=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
resourceworks 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 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. 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.
- A real agent. Sierra says Meta's Muse looks for
poppy.jsonfirst 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. 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 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.
The full write-ups are public: Draft 0.1, Version 0.3 and Version 1.0.
Frequent questions
How long does it take to implement the Personal Agent Protocol? +
What is the minimum a company has to do? +
Do I need to build an OAuth server? +
Is there an official tool to help? +
How do I test a Personal Agent Protocol implementation? +
Do I have to verify the Poppy-Session header on every request? +
Should I offer Device Sign-In? +
What happens when the protocol changes? +
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.
- The Personal Agent Protocol, explained What it is, how 1.0 works on the wire, and what changed from the drafts.
- Personal Agent Protocol vs MCP What each one does, and how one endpoint serves both.
- Who supports Poppy The companies and agents we could verify, with the files they serve.
Sources and further reading
- Personal Agent Protocol specification, Version 1.0 ↗ The requirements this page orders into stages.
- Personal Agent Protocol guides, for companies ↗ Recommended practice for each capability, from the maintainers.
- Company implementation kit ↗ The official skill and validator for building the company side.
- RFC 8628: OAuth 2.0 Device Authorization Grant ↗ The grant behind Device Sign-In.
- RFC 9728: OAuth 2.0 Protected Resource Metadata ↗ The document that links your domain to your sign-in server.
- Stacktree implementation report, Version 1.0 ↗ Our latest write-up for the maintainers, with what changed for us in 1.0.
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 →