A small, zero-dependency Node CLI and library that checks and generates
/.well-known/poppy.json, the discovery file of the Personal Agent Protocol by Sierra and Meta.Created and invented by Matteo Perino (LinkedIn). Built and maintained by GeoSuite(Matteo Perino).
Try it online: enter a site, see whether its poppy.json works, or build one
No install: the page checks the live file the way an agent would and builds a new one in your browser, ready to copy or download. Or run the CLI below.
Poppy Check is an independent GeoSuite tool for the Personal Agent Protocol by Sierra and Meta. It is not affiliated with, or endorsed by, either company.
The Personal Agent Protocol
("Poppy", draft 0.3, October 2026, by Sierra and Meta) is how a person's own
AI agent finds a company, signs in for that person over OAuth and acts for them.
It all starts from one JSON file the company publishes at
https://<domain>/.well-known/poppy.json.
That file names the organization and the ways an agent can work with it: a
conversation endpoint, MCP servers or OpenAPI descriptions, and a browser
session endpoint. A company whose customers sign in also names its OAuth issuer
in the domain's protected resource metadata (RFC 9728,
/.well-known/oauth-protected-resource), and the issuer must list the domain
in the protected_resources field of its RFC 8414 metadata, or agents will not
trust it. A company with no sign-in needs neither: agents use it signed out.
GeoSuite helps brands measure and improve how AI engines (ChatGPT, Perplexity,
Gemini, Google AI Overviews) describe and recommend them. Personal agents are
the next step: once an assistant has chosen a company, a poppy.json is what
lets it actually do something there for the customer. The standard is new, so
most sites do not have the file yet; this tool makes it a ten-minute job and
checks it the same way GeoSuite's audit does.
Requires Node.js 20 or later (uses the native fetch API). No runtime
dependencies.
# Run without installing
npx @geosuite/poppy-json check acme.com
# Or install globally
npm install -g @geosuite/poppy-json
poppy-json --help
# Or as a project dev dependency
npm install --save-dev @geosuite/poppy-jsonBoth poppy-json and geosuite-poppy-json are installed as commands.
npx @geosuite/poppy-json check acme.comReads https://acme.com/.well-known/poppy.json and checks it the way an agent
would: protocol version (0.3), organization domain against the host that
served the file, at least one channel, then the discovery of the sign-in
server: the domain's protected resource metadata, and the issuer's RFC 8414
metadata (issuer, protected_resources, endpoints, grant_types_supported). Exit code 0 when valid, 1 when invalid or not published,
2 on a usage error, so it fits a CI step after a deploy.
poppy.json for acme.com: valid, a personal agent can use it
https://acme.com/.well-known/poppy.json
Protocol version 0.3
Domain acme.com
Sign-in server https://auth.acme.com
Sign-in types direct, device
Channels conversation (poppy), MCP server
Add --json for the raw result.
npx @geosuite/poppy-json validate ./public/.well-known/poppy.json --domain acme.comShape checks only, no network. --domain is the host the file will be served
on (it defaults to the file's own organization.domain). Pass
--metadata-file <file> to also check the issuer metadata you are about to
publish.
npx @geosuite/poppy-json init \
--name "Acme" \
--domain acme.com \
--issuer https://auth.acme.com \
--mcp https://acme.com/mcp \
> poppy.jsonThe poppy.json goes to stdout (or --out <file>). With --issuer, the two
OAuth metadata documents go to stderr, each with the exact URL it must be
served at: the domain's protected resource metadata and the snippet for the
issuer's metadata. --metadata prints only the issuer's snippet, as JSON.
| Flag | Default | Description |
|---|---|---|
--name <text> |
required | organization.name, shown to the person. |
--domain <host> |
required | organization.domain, the host that serves the file. Keep www. if the site lives there: agents compare it with the host after redirects. |
--issuer <https-url> |
none | auth.issuer, your OAuth issuer, kept exactly as given. Leave it out if customers do not sign in through agents. |
--sign-in <list> |
direct |
Any of direct, device, mediated, comma-separated. Needs --issuer. They become the issuer's grant_types_supported; mediated also adds the mediated-sign-in extension, with email and password fields. |
--scopes <list> |
none | The scopes mediated sign-in can grant (required with mediated), also listed in scopes_supported. |
--agent <https-url> |
none | A poppy conversation endpoint (agent.protocols). |
--mcp <https-url> |
none | A remote MCP server. Repeatable. --mcp-description <text> sets its description. |
--openapi <https-url> |
none | An OpenAPI description. Repeatable. --openapi-description <text> sets its description. |
--browser <https-url> |
none | web.browser_session_endpoint. |
--out <file> |
stdout | Write poppy.json to a file. |
--metadata |
off | Print only the issuer metadata snippet. Needs --issuer. |
At least one channel (--agent, --mcp, --openapi or --browser) is required.
With an issuer, agents find it in two steps. First the domain names it, in its
RFC 9728 protected resource metadata
at https://acme.com/.well-known/oauth-protected-resource:
{
"resource": "https://acme.com",
"authorization_servers": ["https://auth.acme.com"]
}Then the issuer confirms the domain, in its
RFC 8414 metadata at
https://auth.acme.com/.well-known/oauth-authorization-server:
{
"issuer": "https://auth.acme.com",
"protected_resources": ["https://acme.com"],
"grant_types_supported": ["refresh_token", "authorization_code"]
}grant_types_supported must include refresh_token, and says which sign-in
types you offer: authorization_code for direct,
urn:ietf:params:oauth:grant-type:device_code for device. The spec also
requires an https token_endpoint and revocation_endpoint, plus
authorization_endpoint for direct sign-in and device_authorization_endpoint
for device sign-in. Your server has those already; init reminds you which
ones apply, and check fails without them.
Without an issuer, publish nothing at /.well-known/oauth-protected-resource:
the 404 tells agents there is no sign-in.
The checker returns the same codes as GeoSuite's audit and the AI Readiness Check:
| Code | Meaning |
|---|---|
not_an_object |
the file is not a JSON object |
missing_protocol_version |
the protocol version is missing |
unsupported_version |
the protocol version is not 0.3, the draft agents follow today |
missing_organization |
the organization name or domain is missing |
domain_mismatch |
the declared domain is not the host that serves the file |
invalid_agent_protocol |
a conversation channel has no type or no https address |
invalid_api_entry |
an API has no type, address or description |
invalid_browser_session_endpoint |
the browser session address is not https |
no_channels |
it declares no channel (conversation, API or website) |
invalid_auth_issuer |
auth.issuer is not an https address |
sign_in_conflict |
sign-in is turned off (auth.disabled), but the file still offers it |
not_https |
the file goes through a non-https address |
wrong_final_path |
the redirects end on an address other than /.well-known/poppy.json |
protected_resource_unreachable |
the domain's /.well-known/oauth-protected-resource does not respond |
protected_resource_invalid |
the domain's /.well-known/oauth-protected-resource cannot be read, or names another resource |
missing_auth_issuer |
the domain declares more than one authorization server, and auth.issuer does not say which one agents use |
issuer_not_listed |
auth.issuer is not among the authorization servers the domain declares |
sign_in_without_issuer |
the file offers sign-in, but the domain names no sign-in server |
issuer_metadata_unreachable |
the sign-in server metadata does not respond |
issuer_metadata_invalid |
the sign-in server metadata cannot be read |
issuer_mismatch |
the sign-in server declares a different issuer |
domain_not_in_issuer |
the sign-in server does not list this domain in protected_resources |
missing_token_endpoint |
the sign-in server does not say where agents get their tokens (an https token_endpoint) |
missing_revocation_endpoint |
the sign-in server does not say where access is revoked (an https revocation_endpoint) |
invalid_grant_types |
the sign-in server does not list grant_types_supported with refresh_token |
missing_authorization_endpoint |
the sign-in server offers authorization_code, but has no https authorization_endpoint |
missing_device_authorization_endpoint |
the sign-in server offers the device code grant, but has no https device_authorization_endpoint |
A missing file is not an issue: check reports it as "not published".
import {
probePoppy,
validatePoppyDocument,
checkIssuerMetadata,
resolveIssuer,
issuerMetadataUrl,
generatePoppy,
explainIssue,
} from '@geosuite/poppy-json';
// Live check, the way an agent does it. Never throws.
const result = await probePoppy('acme.com');
// { present, valid, url, status, issues, protocolVersion, organizationDomain,
// issuer, signInTypes, signInDisabled, signedInAccess, apiTypes,
// hasConversation, hasBrowserSession }
// Offline shape checks for a document and the host it will be served on.
const { valid, issues } = validatePoppyDocument(json, 'acme.com');
issues.map((code) => explainIssue(code, 'en'));
// Build a document and the two OAuth metadata documents.
const { json: text, protectedResource, metadata } = generatePoppy({
name: 'Acme',
domain: 'acme.com',
issuer: 'https://auth.acme.com',
signIn: ['direct'],
apis: [{ type: 'mcp', url: 'https://acme.com/mcp', description: 'Orders and returns' }],
});
// protectedResource.url -> https://acme.com/.well-known/oauth-protected-resource
// metadata.url -> https://auth.acme.com/.well-known/oauth-authorization-server
// metadata.json -> { "issuer": ..., "protected_resources": ["https://acme.com"], ... }
// Both are null without an issuer.generatePoppy throws an Error with a code (missing_name,
invalid_issuer, no_channels, ...) when the input cannot make a valid file.
Its output always passes validatePoppyDocument for the same domain.
- Running the protocol. This tool checks and writes the discovery file; it does not sign in, start conversations or call your APIs.
- Scopes and extensions. The checker reports which of
direct,deviceandmediateda company offers, like GeoSuite's audit, but does not check scope descriptions,scope_hints, the mediated sign-in fields or other extensions.
See CONTRIBUTING.md. Issues and PRs welcome: please open an issue first for non-trivial changes so we can discuss scope.
poppy-json is part of a small family of zero-dependency CLIs we maintain to make Generative Engine Optimization (GEO) measurable from the terminal:
@geosuite/ai-crawler-bots: curated AI bot user-agent list with a CLI that tells you whether GPTBot, ClaudeBot, PerplexityBot and friends can read your site and where the block came from.@geosuite/llms-txt-generator: turn asitemap.xmlinto anllms.txt.@geosuite/schema-templates: copy-paste-ready schema.org JSON-LD templates with a local validator.@geosuite/sitemap-builder: crawl a site and emit a validsitemap.xml, for sites that ship without one.
All of them, plus a single AI Readiness Check, live at tools.trygeosuite.it.
Created and invented by Matteo Perino: LinkedIn · matte97.p@gmail.com.
Ideated, designed and validated by Matteo Perino. Implementation written with AI assistance, maintained under GeoSuite.
MIT © 2026 Matteo Perino and GeoSuite
If poppy-json is useful, give it a star: it helps other people find the toolkit.
This is part of the open-source toolkit behind GeoSuite, the platform that measures and improves how AI engines (ChatGPT, Gemini, Claude, Perplexity) cite your brand. Explore the platform
Built by Matteo Perino: matteoperino.dev