Agent Adapt

Caches, CDNs and security plugins Free

Which paths to exclude from page caches, CDNs and firewalls so personal agents can reach your store, and how to tell when something is in the way.

Updated October 12, 2026

Agent Adapt works with page caches and CDNs. Its answers to agents are marked private, so a well-behaved cache never stores them. Problems come from caches and firewalls that intercept requests before WordPress sees them.

Exclude these paths

From page caching, and from firewall or bot-blocking rules:

  • /.well-known/ (the discovery documents, including poppy.json)
  • /agent-adapt/ (sign-in, the token endpoint, checkout links and, with Pro, the MCP server)
  • /wp-json/agent-adapt/ (the agent API)

Agents are programs, not people, so challenge pages, CAPTCHAs and JavaScript checks stop them completely. If your CDN or security plugin has a bot-fighting mode, make sure it skips these paths.

Signs something is in the way

  • Site Health says "Your discovery documents answer" failed. Something returned the wrong thing for /.well-known/poppy.json or the OAuth metadata. Open https://your-store/.well-known/poppy.json in a private window: you should see JSON naming your store, not an HTML page.
  • Site Health says the Authorization header doesn’t reach WordPress. Your server strips it. See Site Health checks for the one-line fix.
  • Agents report errors after a while, not straight away. A cache may be serving a stale copy of the discovery documents. Purge it and add the exclusions above.

The cart is safe

An agent’s browser, when it has one, carries WooCommerce’s session cookie like any shopper’s, so caches that skip pages for shoppers with a cart skip them for agents too. A customer’s own cart is never touched by an agent’s visit until the customer opens a checkout link.

Related guides

Still stuck? Email [email protected].