Skip to main content
Version: 3.1.0

Dealer-domain discovery

Start at the dealership's website. Follow explicit links to working services. The service can run on a provider's infrastructure; the dealership remains the discoverable identity.

A dealer domain links its Agent Card, Poppy document and llms.txt to one automotive contract and three interfacesOpen full-size diagram

Publish three entry points​

Dealer URLWhat an agent learns
/.well-known/agent-card.jsonA2A endpoint, selected AAP version, implemented skills, MCP URL and search capabilities
/.well-known/poppy.jsonPAP 0.3 organization, issuer, native OpenAPI and links to A2A/MCP
/llms.txtA short, readable index of those interfaces and their access requirements

All three MUST be public over HTTPS. The two discovery documents MUST return JSON. llms.txt MUST return UTF-8 Markdown as text/plain or text/markdown. None of these requests submits a lead or needs a shopper's personal information.

AAP does not define a universal MCP well-known path. The exact MCP endpoint comes from these documents. A static tool catalog is not an MCP server.

Agent Card: identity and capabilities​

Use the complete Agent Card example and schema. Replace the example identity and URLs, then retain only implemented skills.

An Agent Card separates dealer identity, A2A transport, the AAP contract and actual search capabilitiesOpen full-size diagram

The card remains an ordinary A2A 1.0 Agent Card. AAP requires:

  1. Exactly one AAP entry in capabilities.extensions[], with required: true and this contract's URI:

    https://autoagentprotocol.org/extensions/aap/v3.1

  2. A JSONRPC interface with protocolVersion: "1.0" in supportedInterfaces[]. Prefer it first. Additional A2A interfaces must expose equivalent functionality under A2A's rules. MCP and PAP are not A2A protocolBinding values.

  3. One or more implemented AAP skills in skills[], with unique IDs and the same subset in the AAP extension's params.skills.

  4. Complete extension params following aap-extension-params.schema.json:

Params fieldRequired meaning
idStable deployment identifier, never a shopper identifier
version, schema_base_urlSelected AAP release and its immutable schema base
skillsCanonical request/response schema URLs for every implemented skill
skills["inventory.search"].capabilitiesActual filters, sort fields, defaults, limits and dealer/aggregate scope
mcpExact URL, streamable-http, supported MCP revisions and public_read
poppyCanonical dealer-domain /.well-known/poppy.json URL
llms_txtCanonical dealer-domain /llms.txt URL

Search defaults MUST be usable: default_sort.field belongs to sort_fields, and default_limit does not exceed max_limit. Feature filters require inventory.facets so a client can discover supported feature codes. An unsupported filter is an explicit error, never silently ignored. See search semantics.

A facets-only deployment omits inventory.search and its capabilities. It accepts USD/CAD and mi/km contexts with USD/mi defaults under the facets-only fallback; clients can explicitly request CAD/km without a search declaration.

The card's software version is independent of AAP params.version. The A2A extension URI, not the software version, selects the automotive contract.

Poppy: an authenticated native API​

The Poppy example publishes PAP 0.3, an issuer and a native OpenAPI interface. Its extensions["autoagentprotocol.org/aap"] links the paired Agent Card, the same MCP URL, AAP release and llms.txt.

The public MCP pointer belongs in that AAP extension. A top-level apis entry with type: "mcp" additionally promises PAP Session Tokens, protected-resource metadata and scope enforcement. Only advertise it when those behaviors exist. See native PAP MCP.

For redirects, PAP organization identity follows the final HTTPS discovery host, comparing case only; www is a distinct host. The final URL keeps exactly /.well-known/poppy.json without a query. The issuer must authorize that domain through protected_resources, with an entry exactly https://{domain} (hostname case ignored; no port, path or trailing slash). Keep canonical links consistent after redirects and use one issuer per independent Company. Full rules are in PAP discovery.

llms.txt: a useful index, not registration​

A short dealer llms.txt index links the exact MCP endpoint, A2A and PAP discovery, API documentation and inventoryOpen full-size diagram

The llms.txt proposal provides a small Markdown index. It does not make every agent automatically discover or trust a website. AAP 3.1 requires this index as an additional entry point, alongside working protocol discovery.

Start from the dealer llms.txt example. Include the dealer name, selected AAP version, exact MCP URL, public/authenticated access requirements, Agent Card, Poppy document, deployment-specific OpenAPI and a link to human-readable inventory. State that lead submission needs explicit customer contact consent.

Use descriptive Markdown links rather than an unstructured list of URLs. Keep it short; link to details. If Markdown page representations exist, advertise them with registered HTML link relations:

<link rel="describedby" type="text/plain" href="/llms.txt" />
<link rel="alternate" type="text/markdown" href="/inventory.md" />

HTTP Link headers can advertise the same relationships. Only publish an alternate URL that actually serves a corresponding Markdown page. Do not describe a private rel="mcp" convention as a universally supported standard.

One declaration, three equivalent surfaces​

MCP, A2A and PAP expose equivalent skills, search capabilities, inventory, pricing, consent and outcomesOpen full-size diagram

The AAP skill subset, automotive schemas, inventory visibility, search capabilities, pricing and consent rules MUST agree across MCP, A2A and PAP OpenAPI. A native PAP MCP entry, when present, MUST use the advertised MCP URL as both its url and resource.

MCP tools/list MUST expose the same AAP subset, with the same version and schema metadata. Its search tool's _meta["autoagentprotocol.org/aap"].capabilities MUST match the Agent Card. The native OpenAPI operations MUST match that subset and its x-aap-extension MUST match the A2A extension URI.

Cache discovery using accurate HTTP cache headers, ETags and reasonable lifetimes. Invalidate it when endpoints, versions or capabilities change. Verify the linked service before switching discovery. Do not advertise a future implementation or a template server.

Transport and authorization​

Every published endpoint and redirect MUST use HTTPS. Loopback HTTP is allowed only in a local development harness. Do not embed credentials in discovery URLs.

  • MCP: public inventory reads are recommended. Protected access follows MCP OAuth discovery and the endpoint's declared authorization policy.
  • A2A: follow securitySchemes / securityRequirements. Portable clients send A2A-Version: 1.0 and the exact A2A-Extensions URI; a contract-pinned AAP endpoint also accepts their omission. If an interface declares tenant, echo it in every request.
  • PAP OpenAPI: use a verified PAP Session Token and DPoP, including for signed-out shoppers.

A link does not authorize credential forwarding. Authenticate to the selected resource under its own rules. See migration for separate version-specific cards and endpoints, and conformance for runtime acceptance.