How the protocol works

Poppyseed implements the Personal Agent Protocol (PAP). We call it the Poppy protocol, after the file every site publishes: poppy.json. The exact rules are in the spec.

Three parties

• The User: a person, like Maya.
• Their Personal Agent: software acting for that one person, such as an assistant app.
• A Company: your site.

Without the protocol, agents scrape pages and type the person's password into your login form. With it, you decide what agents can do, and the person approves anything that matters.

Discovery

Your site describes itself at /.well-known/poppy.json: who you are, your OAuth server, the sign-in types and scopes you offer, your APIs (MCP and OpenAPI) and extensions. Poppyseed generates it from your config.

Sessions

Every visit is a Session: one User, one Company, one Personal Agent. It starts signed out.

Agents have no password. An agent proves who it is with a key: it publishes its public keys at its client_id URL and signs an assertion. You check it and issue a Session Token:

Token	Used at	Bound to
DPoP	OpenAPI, operations, conversations	The agent's key. Each request carries a fresh proof, so a stolen token is useless.
Bearer	MCP	The MCP server's URL.

Tokens are short-lived and sealed: agents can't read or change them. An agent's browser can join the same Session (web browsing).

Signing in

A tool's scope, such as poppy:read, says it needs the User's account. A signed-out Session that calls it gets sign_in_required, and the agent signs the person in one of three ways:

Sign-in	The person	Use when
Direct	approves on your consent page	the agent can open a browser
Device	enters a short code on your site	the agent runs on a phone, speaker or chat app
Mediated	gives the agent their credentials	the other two can't work; keep scopes narrow

Each ends with a signed-in Session Token and an Account Token, so next time the agent signs in without asking. People see and disconnect agents in their account settings.

Tools

A tool has a name, description, input schema and scope. Each one is served twice, as an MCP tool and as POST /poppy/tools/{name}, and gets a context saying who is calling.

Operations

Anything with consequences (a booking, a charge, a cancellation) is an operation, an extension agents opt into:

1. Propose. You work out the terms without changing anything, and answer with an operation: id, revision, summary, terms.
2. Approve. The agent shows the summary to the person. Changed terms make a new revision; only the latest can be confirmed.
3. Confirm. You perform it at most once, however many times it is confirmed.
4. Track. It ends succeeded, failed, cancelled or expired. failed means it certainly didn't happen; an unknown outcome stays in_progress.

Conversations

Agents can talk to your own agent, the Company Agent, which uses your tools under the Session's scopes. If the person needs a human, the conversation waits in your staff inbox.

What you write

Poppyseed does all of the above on Web Request and Response. You write the tools, say who is signed in to your site, and decide what each scope allows. The conformance suite checks the result against the spec.