introducing poppyseed, implementation of the Personal Agent Protocol draft (0.1) for Next.js.

describe your tools, add one route, and agents that support the protocol can start using your site.

npm install poppyseed

https://t.co/M3ZOTJTpse https://t.co/o42kk27sJ7

Poppyseed · Personal Agent Protocol for Next.js

Source: https://www.withpoppyseed.dev/

Let personal agents use your site.

Poppyseed implements thePersonal Agent Protocol(Poppy for short) for Next.js. Install one package and add one route. AI agents can then find your site, sign people in and ask them before they buy.

npm install poppyseed zod

Paste it into Claude Code, Cursor or Codex, or

read it first``` Add the Personal Agent Protocol (Poppy for short; spec: https://personalagentprotocol.org/docs/spec) to this Next.js App Router app with the poppyseed package, so people’s personal AI agents can use it.

1. Run: npm install poppyseed zod Then: echo “POPPYSEED_SECRET=$(openssl rand -base64 48)” >> .env.local

2. Create poppyseed.config.ts at the project root. Pick 2-4 useful read-only tools built on this app’s existing data and functions:

import { definePoppyseed, memoryStore, tool, ToolError } from “poppyseed”; import { z } from “zod”;

const dev = process.env.NODE_ENV === “development”;

export const poppyseed = definePoppyseed({ // domain must match the host agents use: localhost in development. organization: { name: “”, domain: dev ? “localhost” : “<production domain, e.g. example.com>” }, secret: process.env.POPPYSEED_SECRET!, store: memoryStore(), …(dev && { baseUrl: “http://localhost:3000”, dev: { allowInsecureClients: true } }), // use the dev server’s real port tools: { example: tool({ description: “What it does, for an agent”, scope: null, // public, no sign-in input: z.object({ /* inputs / }), run: async (input) => ({ / JSON result */ }), // throw new ToolError(“…”) for errors the agent should see }), }, });

3. Create app/api/poppyseed/[…path]/route.ts (no other exports):

import { toNextHandlers } from “poppyseed/next”; import { poppyseed } from “@/poppyseed.config”;

export const { GET, POST, DELETE } = toNextHandlers(poppyseed);

4. In next.config.ts, keep every existing option and wrap the export: import { withPoppyseed } from “poppyseed/next/config”, then export default withPoppyseed(nextConfig).

5. Verify: start the dev server, then run npx poppyseed agent http://localhost: ‘’ for each tool. It exits 0 only if discovery and the tool call succeed; fix anything until it does. Then run npm run build.

Tell me to set POPPYSEED_SECRET in my hosting provider’s environment before deploying. For tools that need the person’s account, purchases people approve, a support agent, or serverless hosting (postgresStore), see https://withpoppyseed.dev/docs/guides and https://withpoppyseed.dev/docs/deployment.

Prefer doing it by hand? Follow the[quickstart](https://www.withpoppyseed.dev/docs/quickstart)\.

poppyseed\.config\.tsroute\.tsnext\.config\.ts

import { definePoppyseed, memoryStore, tool } from “poppyseed”;import { z } from “zod”;const dev = process.env.NODE_ENV === “development”;export const poppyseed = definePoppyseed({ organization: { name: “Seed Café”, domain: dev ? “localhost” : “seed.cafe” }, secret: process.env.POPPYSEED_SECRET!, store: memoryStore(), …(dev && { baseUrl: “http://localhost:3000”, dev: { allowInsecureClients: true } }), tools: { menu: tool({ description: “Drinks on the menu today”, scope: null, // anyone, signed in or not input: z.object({ size: z.enum([“small”, “large”]) }), run: ({ size }) => ({ drinks: menu(size) }), }), },});

app/api/poppyseed/\[\.\.\.path\]/route\.ts

import { toNextHandlers } from “poppyseed/next”;import { poppyseed } from “@/poppyseed.config”;export const { GET, POST, DELETE } = toNextHandlers(poppyseed);

import { withPoppyseed } from “poppyseed/next/config”;// Only /.well-known/poppy.json, /oauth/, /mcp and /poppy/// go to Poppyseed. Every other URL stays yours.export default withPoppyseed(nextConfig);

`npx poppyseed agent http://localhost:3000 menu`

1. Found**Seed Café**at /\.well\-known/poppy\.json
2. Started a session, signed with its own key
3. Listed**1 tool**over MCP and OpenAPI
4. Called**menu**

{ “drinks”: [{ “name”: “Flat white”, “price”: 4.2 }] }

## Turn on more as you need it

poppyseed\.config\.ts

export const poppyseed = definePoppyseed({ organization: { name: “Poppy Travel”, domain: “poppy.travel” }, secret: process.env.POPPYSEED_SECRET!, store: memoryStore(), store: postgresStore(pool), accounts: { current: yourLogin, signInUrl: (to) => /login?return_to=${to} }, signIn: { device: { scopes: [“poppy:read”, “poppy:write”] } }, conversations: { agent: claudeAgent({ instructions: “Help travelers.” }) }, tools: { search_flights: tool({ description: “Search one-way flights”, scope: null, input: z.object({ from: z.string(), to: z.string(), date: z.iso.date() }), run: (input) => ({ offers: searchFlights(input) }), }), my_trips: tool({ description: “Your upcoming trips”, scope: “poppy:read”, input: z.object({}), run: (_, ctx) => ({ trips: tripsOf(ctx.account.id) }), }), book_flight: tool({ description: “Book a flight offer”, scope: “poppy:write”, input: z.object({ offer_id: z.string() }), operation: { propose: ({ offer_id }) => quote(offer_id), // { summary, terms } perform: ({ id, terms }, ctx) => book(ctx.account.id, terms, id), }, }), },});

## See it in 37 seconds

## Checked against the spec

**98**conformance checks pass and none fail over HTTP through a real Next\.js server, covering**147**rules of the[Personal Agent Protocol](https://personalagentprotocol.org/docs/spec)\. Each check is proven by breaking its rule on purpose and watching it fail\.

Run the same checks against your own site:

`npx poppyseed check https://your\.site`