Personal Agent Protocol
Why the shop uses Poppy, and how Sessions, grants and agent channels fit together.
Personal Agent Protocol (Poppy) describes how software acting for a person works with a company on that person’s behalf. This shop implements the company side of draft 0.1. The protocol specification defines the wire format; this page explains the model and points to the implementation documentation.
Why it is part of this demo
An agent needs its own identity and permissions instead of borrowing a person’s credentials. Poppy connects that identity across APIs, a browser and conversations with the company. A person can approve access, see which agent acted, and revoke its grant. Account Tokens let the agent return for later tasks without asking the person to sign in each time.
Sessions and grants
| Concept | Role |
|---|---|
| Personal Agent | Software acting for one User. Its client ID is the URL of its metadata document, which identifies its signing keys. |
| Company | The shop, with discovery at /.well-known/poppy.json, published resources and a Company Agent called Fern. |
| Session | One agent’s interaction with the Company for a User. It starts identified but signed out; signing in gives it account permissions. |
| Account Token | A credential for returning with an approved account grant. Ending one Session leaves this grant usable; disconnecting the grant revokes it and its Sessions. |
| Permissions | poppy:read for account reads, poppy:write for supported changes, and checkout for purchases with a saved card. Effective authority is limited by both the token and the live Session. |
| Channels | Direct API calls, MCP, an agent browser and conversations share the Session’s identity and authority. Signed-in agents use the account cart; signed-out agents use a Session cart. |
The protocol defines Direct, Device and Mediated sign-in. The Auth0 proxy handles these flows, grants and Sessions alongside Auth0; it issues credentials and answers introspection. The Shop API owns the shared commerce operations, conversations and Fern. The storefront owns browser sessions and UI. The MCP server adapts tools to the Shop API. The Auth0 proxy never proxies commerce traffic.
An agent browser joins a Poppy Session through a signed browser assertion. The shop sets its browser cookie and shows the agent banner. The cookie carries the Poppy Session’s authority; it does not become an Auth0 browser sign-in. The account’s Sessions page combines the two sources so the person can manage them together.
First sign-in
An agent first discovers the Company and creates an identified, signed-out Session. It can use permitted base capabilities before it has account access. Direct sign-in uses an authorization-code flow with PKCE; Device sign-in lets the person approve the request in their own browser. The protocol also defines Mediated sign-in.
After the person signs in and approves scopes, the agent receives an Account Token and Session credentials for the approved account. Later tasks can use the Account Token to sign in a Session without repeating approval. Direct API calls use DPoP-bound credentials; MCP uses credentials for the exact MCP resource. An agent browser joins through a browser assertion. These channels preserve the same Session authority.
Ending one Session ends that interaction. Disconnecting the account grant revokes the Account Token and all Sessions using it. Auth0 browser sign-ins are a separate source: ordinary MCP OAuth has no Poppy Session, and a Poppy agent’s browser cookie does not become the person’s Auth0 cookie. See session controls and logout propagation for enforcement and timing limits.
WebMCP and payments
WebMCP exposes tools to an assistant inside the browser being used. Poppy identifies an external Personal Agent. The webshop supports both: WebMCP tools act as the current browser visitor, including that visitor’s Poppy permissions when the browser belongs to an agent.
A person adds a saved card through Stripe Elements. Browser checkout can complete a bank challenge; an agent
uses the saved card off-session under checkout and cannot complete that challenge. Payments that need it fail
with payment_requires_action. Charge and refund retries use payment idempotency keys; checkout requests do not
have a general idempotency-key contract.
Implementation references
- Getting started: run the local shop and prepare your own deployment.
- System map and components: who owns each capability.
- Poppy request flows: token verification, browser forwarding, authority and conversations.
- Poppy compliance: protocol requirements, implementation limitations and tests.
- Invited agents: independent agent identities and delegated browser sessions.
- MCP clients: standard OAuth and Session-backed access to the canonical MCP resource.