Add an /agents Page to Your Site — The Capability Manifest That Tells Agents What You Do

The menu of everything that's open for business.

Before an agent can buy from you, search your catalog, or initiate a return on a customer's behalf, it must first understand that it can do those things and how. Today, agents either guess at API endpoints by reading docs pages written for humans, hit trial-and-error against undocumented paths, or simply skip sites that don't expose structured capability information. The /agents page solves this. It is not a marketing page. It is an operator-to-machine declaration: here is who we are, here is what you can call, here is how to authenticate, here is where the sandbox lives.

The AgentMall Roadmap names three ways the internet fails agents. Discovery addresses the first failure: agents can't find products. The four-file discovery quadrant is the complete solution — each file handling a different layer of the information a visiting agent needs. Every agent-ready site needs all four.

Each file should reference the others. The robots.txt should include an # AgentManifest: comment pointing to /agents.json. The llms.txt blockquote summary should mention that a capability manifest exists. The sitemap.xml should include the /agents URL. And /agents.json should declare the sitemap URL so any agent reading the manifest can immediately locate your content map.

What /agents Is Not

Eight sections a production /agents.json must cover.

The following eight sections cover every field a production /agents.json should include. Each section gives the field name, whether it is required or optional, a complete example value using hypothetical example domains, and what an agent does with it. All sample data uses meridiansupply.example.com — not a real merchant.

Field 1 — identity

Who operates this site. Agents use this to log attribution, confirm they're talking to the right service, and route abuse reports.

"identity": {
  "operator_name": "Meridian Supply Co.",
  "legal_entity": "Meridian Supply Co., LLC",
  "site_url": "https://meridiansupply.example.com",
  "agent_contact": "agents@meridiansupply.example.com",
  "abuse_contact": "abuse@meridiansupply.example.com",
  "gdpr_dpo_contact": "privacy@meridiansupply.example.com",
  "jurisdiction": "US-DE"
}

Field 2 — capabilities

A verb list of every action an agent is permitted to invoke. Keep it tight — only list what is actually implemented and tested. A capability list that advertises initiate_checkout when checkout is not agent-accessible will cause silent failures.

"capabilities": [
  "search_products",
  "get_product",
  "check_inventory",
  "get_pricing",
  "initiate_checkout",
  "get_order_status",
  "request_return",
  "subscribe_to_restock",
  "get_shipping_estimate",
  "get_return_policy"
]

Field 3 — endpoints

Where to make calls. Agents use this to route requests without parsing human docs. Include every protocol surface your site exposes.

"endpoints": {
  "mcp_server": "https://mcp.meridiansupply.example.com",
  "rest_base": "https://api.meridiansupply.example.com/v1",
  "graphql": "https://api.meridiansupply.example.com/graphql",
  "openapi_spec": "https://api.meridiansupply.example.com/openapi.json",
  "sitemap": "https://meridiansupply.example.com/sitemap.xml"
}

Field 4 — auth

The full OAuth 2.0 declaration. See Section 8 for the complete OAuth deep dive. Agents use this to know which flows to initiate and where to register dynamically via RFC 7591 DCR.

"auth": {
  "type": "oauth2",
  "flows_supported": ["authorization_code", "client_credentials"],
  "pkce_required": true,
  "pkce_methods": ["S256"],
  "authorization_server_metadata": "https://auth.meridiansupply.example.com/.well-known/oauth-authorization-server",
  "authorize_url": "https://auth.meridiansupply.example.com/authorize",
  "token_url": "https://auth.meridiansupply.example.com/token",
  "registration_endpoint": "https://auth.meridiansupply.example.com/register",
  "scopes_available": [
    "products:read",
    "inventory:read",
    "orders:write",
    "returns:write",
    "checkout:initiate"
  ],
  "api_key_acquisition": "https://meridiansupply.example.com/developers/api-keys",
  "agent_identity_requirements": "Agents must present a signed JWT assertion (RFC 7521) in the token request."
}

Field 5 — sandbox

Test before going live. Agents use the sandbox to validate tool calls without side effects. Include real test SKUs — an empty sandbox is useless.

"sandbox": {
  "test_endpoint": "https://sandbox-api.meridiansupply.example.com/v1",
  "test_mcp_server": "https://sandbox-mcp.meridiansupply.example.com",
  "test_credentials_acquisition": "https://meridiansupply.example.com/developers/sandbox",
  "test_data": {
    "products": ["SKU-TEST-001", "SKU-TEST-002", "SKU-TEST-OUTOFSTOCK"],
    "orders": ["ORD-TEST-12345"],
    "return_eligible_order": "ORD-TEST-99999"
  },
  "dry_run_mode": true,
  "dry_run_header": "X-Dry-Run: true",
  "notes": "Sandbox orders do not trigger fulfillment. Payment tokens are Stripe test keys only."
}

Field 6 — policies

Machine-readable links to the policies an agent needs when making decisions on a user's behalf. Prefer JSON versions so agents can parse specific fields (e.g., return window in days) rather than parsing HTML prose.

"policies": {
  "return_policy": "https://meridiansupply.example.com/policies/returns.json",
  "return_policy_human": "https://meridiansupply.example.com/returns",
  "shipping_policy": "https://meridiansupply.example.com/policies/shipping.json",
  "privacy_policy": "https://meridiansupply.example.com/privacy",
  "terms_of_service": "https://meridiansupply.example.com/terms",
  "agent_usage_policy": "https://meridiansupply.example.com/policies/agent-usage"
}

Field 7 — receipts

How an agent subscribes to post-action events and generates an audit trail. Agents acting on behalf of users need receipts for the conversation record.

"receipts": {
  "webhook_subscription_endpoint": "https://api.meridiansupply.example.com/v1/webhooks",
  "webhook_events": [
    "order.created",
    "order.fulfilled",
    "order.cancelled",
    "return.initiated",
    "return.completed"
  ],
  "event_schema_url": "https://api.meridiansupply.example.com/v1/webhooks/schema.json",
  "audit_trail_format": "JSON Lines (NDJSON)",
  "audit_trail_endpoint": "https://api.meridiansupply.example.com/v1/audit-log"
}

Field 8 — sample_queries

Concrete examples of what agents can ask. Include both natural-language prompts and the corresponding MCP tool call or REST request. This is the fastest way to get a new agent client working correctly on day one.

"sample_queries": [
  {
    "description": "Search for a product by keyword",
    "prompt": "Find all blue mountain bikes under $800 in stock",
    "mcp_tool": "search_products",
    "mcp_arguments": {
      "query": "blue mountain bike",
      "max_price": 800,
      "in_stock_only": true
    }
  },
  {
    "description": "Check inventory for a specific SKU",
    "prompt": "How many units of SKU-7721 are available?",
    "mcp_tool": "check_inventory",
    "mcp_arguments": { "sku": "SKU-7721" }
  },
  {
    "description": "Initiate a return",
    "prompt": "Start a return for order ORD-88234, item SKU-7721, reason: defective",
    "mcp_tool": "request_return",
    "mcp_arguments": {
      "order_id": "ORD-88234",
      "sku": "SKU-7721",
      "reason": "defective"
    }
  },
  {
    "description": "Subscribe to restock notification",
    "prompt": "Notify me when SKU-SOLDOUT comes back in stock",
    "mcp_tool": "subscribe_to_restock",
    "mcp_arguments": {
      "sku": "SKU-SOLDOUT",
      "webhook_url": "https://agent-runtime.example.com/webhooks/restock"
    }
  }
]

JSON-only, Markdown summary, or hybrid HTML+JSON.

Three formats are in use. The right answer for most operators is the hybrid approach: a machine-readable JSON file plus a human-readable HTML page, linked together. All examples below use meridiansupply.example.com as the hypothetical operator domain.

Option A: Pure JSON Machine Manifest (/agents.json)

Served with Content-Type: application/json. This is what agents parse programmatically. No prose. Complete runnable example for a hypothetical merchant — all data is fabricated for illustration:

{
  "manifest_version": "1.0",
  "last_updated": "2026-06-01",
  "identity": {
    "operator_name": "Meridian Supply Co.",
    "legal_entity": "Meridian Supply Co., LLC",
    "site_url": "https://meridiansupply.example.com",
    "agent_contact": "agents@meridiansupply.example.com",
    "abuse_contact": "abuse@meridiansupply.example.com",
    "gdpr_dpo_contact": "privacy@meridiansupply.example.com",
    "jurisdiction": "US-DE"
  },
  "capabilities": [
    "search_products",
    "get_product",
    "check_inventory",
    "get_pricing",
    "initiate_checkout",
    "get_order_status",
    "request_return",
    "subscribe_to_restock",
    "get_shipping_estimate",
    "get_return_policy"
  ],
  "endpoints": {
    "mcp_server": "https://mcp.meridiansupply.example.com",
    "rest_base": "https://api.meridiansupply.example.com/v1",
    "graphql": "https://api.meridiansupply.example.com/graphql",
    "openapi_spec": "https://api.meridiansupply.example.com/openapi.json",
    "sitemap": "https://meridiansupply.example.com/sitemap.xml"
  },
  "auth": {
    "type": "oauth2",
    "flows_supported": ["authorization_code", "client_credentials"],
    "pkce_required": true,
    "pkce_methods": ["S256"],
    "authorization_server_metadata": "https://auth.meridiansupply.example.com/.well-known/oauth-authorization-server",
    "authorize_url": "https://auth.meridiansupply.example.com/authorize",
    "token_url": "https://auth.meridiansupply.example.com/token",
    "registration_endpoint": "https://auth.meridiansupply.example.com/register",
    "scopes_available": [
      "products:read",
      "inventory:read",
      "orders:write",
      "returns:write",
      "checkout:initiate"
    ]
  },
  "sandbox": {
    "test_endpoint": "https://sandbox-api.meridiansupply.example.com/v1",
    "test_mcp_server": "https://sandbox-mcp.meridiansupply.example.com",
    "test_data": {
      "products": ["SKU-TEST-001", "SKU-TEST-002", "SKU-TEST-OUTOFSTOCK"],
      "orders": ["ORD-TEST-12345"],
      "return_eligible_order": "ORD-TEST-99999"
    },
    "dry_run_mode": true,
    "dry_run_header": "X-Dry-Run: true"
  },
  "policies": {
    "return_policy": "https://meridiansupply.example.com/policies/returns.json",
    "privacy_policy": "https://meridiansupply.example.com/privacy",
    "agent_usage_policy": "https://meridiansupply.example.com/policies/agent-usage"
  },
  "receipts": {
    "webhook_subscription_endpoint": "https://api.meridiansupply.example.com/v1/webhooks",
    "webhook_events": ["order.created", "order.fulfilled", "return.initiated"]
  },
  "discovery_cross_links": {
    "robots_txt": "https://meridiansupply.example.com/robots.txt",
    "sitemap_xml": "https://meridiansupply.example.com/sitemap.xml",
    "llms_txt": "https://meridiansupply.example.com/llms.txt"
  }
}

Option B: Markdown Summary (/agents.md or the /agents HTML page)

Human-readable version. This is what a developer reads when they visit /agents in a browser. It should summarize the JSON and link to the machine file. Complete runnable example:

# Meridian Supply Co. — Agent Capability Manifest

> Meridian Supply Co. sells outdoor and cycling equipment.
> Agent capability manifest (MCP endpoints, OAuth, sandbox):
>   https://meridiansupply.example.com/agents.json
> Sitemap: https://meridiansupply.example.com/sitemap.xml

## What Agents Can Do Here

- Search products by keyword, category, price, and availability
- Retrieve individual product details and pricing
- Check real-time inventory levels
- Initiate checkout flows (OAuth required)
- Query and manage order status
- Request returns for eligible orders

## Endpoints

| Type       | URL                                                  |
|------------|------------------------------------------------------|
| MCP Server | https://mcp.meridiansupply.example.com               |
| REST API   | https://api.meridiansupply.example.com/v1            |
| GraphQL    | https://api.meridiansupply.example.com/graphql       |
| OpenAPI    | https://api.meridiansupply.example.com/openapi.json  |

## Authentication

OAuth 2.0 Authorization Code (with PKCE) and Client Credentials.
Dynamic Client Registration (RFC 7591) available at:
https://auth.meridiansupply.example.com/register

Authorization server metadata:
https://auth.meridiansupply.example.com/.well-known/oauth-authorization-server

## Full Machine-Readable Manifest

https://meridiansupply.example.com/agents.json

Option C: Hybrid HTML + Linked JSON (Recommended)

The most practical approach for most operators. The /agents URL serves a human-readable HTML page. The HTML page includes a <link> element pointing to /agents.json. The Content-Type for /agents.json must be application/json. This gives browsers a renderable page, LLM crawlers parseable content, and agent runtimes a direct JSON path — all from a single URL pair.

<!-- In the <head> of /agents/index.html -->
<link rel="agent-manifest" href="/agents.json" type="application/json" />

Seven candidate paths — none yet officially standardized.

The ecosystem has not settled on a single canonical URL for the capability manifest. These are the options in active use or active proposal as of mid-2026. The recommendation: publish at both /agents.json and /.well-known/agent.json and add the /.well-known/mcp endpoint when the MCP spec finalizes that path.

Seven domains probed. Zero root-domain manifests found.

All checks performed via curl against production URLs during research for this article (re-verify before launch — this landscape changes fast). For each candidate site, four paths were probed: /agents, /agents.json, /.well-known/mcp, and /.well-known/ai-plugin.json.

The Stripe mcp.stripe.com Production Pattern

Stripe does not publish a /agents capability manifest on the main domain. However, Stripe operates a live production MCP server at mcp.stripe.com. That server returns a valid RFC 8414 OAuth Authorization Server Metadata document at mcp.stripe.com/.well-known/oauth-authorization-server (HTTP 200 confirmed — re-verify before launch). Stripe also publishes agent skill metadata at docs.stripe.com/.well-known/skills/index.json (HTTP 200 confirmed — re-verify before launch).

{
  "issuer": "https://access.stripe.com/mcp",
  "authorization_endpoint": "https://access.stripe.com/mcp/oauth2/authorize",
  "token_endpoint": "https://access.stripe.com/mcp/oauth2/token",
  "registration_endpoint": "https://access.stripe.com/mcp/oauth2/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"]
}

This is the pattern to follow: a dedicated MCP subdomain, RFC 8414 OAuth metadata at /.well-known/oauth-authorization-server, Authorization Code + Refresh Token flows, S256 PKCE, and Dynamic Client Registration at /register. Note that Stripe splits this across mcp.stripe.com rather than the marketing domain — a model that keeps the agent-facing surface separate from consumer-facing URLs.

Four files. Four entry points. One interconnected quadrant.

All four files must reference each other. An agent entering your site at any of the four standard discovery points — robots.txt, sitemap.xml, llms.txt, or /agents.json — should be able to reach all the others within one or two hops. Here is the cross-link pattern for each file, using the hypothetical meridiansupply.example.com domain.

robots.txt Addition

Place this comment near the top of robots.txt, before the first User-agent: directive. It is not a formal robots.txt directive — it is a machine-readable comment. Any agent runtime that parses the full robots.txt body can extract this reference. See the robots.txt + agents.txt spoke for the full bot policy configuration.

# Agent capability manifest
# AgentManifest: https://meridiansupply.example.com/agents.json

User-agent: *
Allow: /

llms.txt Blockquote Addition

The blockquote line that mentions agents.json is the key addition. LLM-powered agents reading llms.txt at inference time will see the capability manifest reference and can fetch it before constructing tool calls. See the Agent-Readable Sitemap spoke for the full llms.txt format.

# Meridian Supply Co.

> Meridian Supply Co. sells outdoor and cycling equipment.
> Agent capability manifest (MCP endpoints, OAuth, sandbox): https://meridiansupply.example.com/agents.json
> Sitemap: https://meridiansupply.example.com/sitemap.xml

## Products
- [Mountain Bikes](https://meridiansupply.example.com/products/mountain-bikes): Full catalog of trail and enduro bikes
- [Cycling Gear](https://meridiansupply.example.com/products/gear): Helmets, clothing, and accessories

## Policies
- [Returns](https://meridiansupply.example.com/returns): 30-day return policy
- [Shipping](https://meridiansupply.example.com/shipping): Delivery times and costs

sitemap.xml Addition

Include both /agents (the human HTML page) and /agents.json so agents running a sitemap pass see the capability manifest URL. This ensures agents that do a full sitemap walk encounter the manifest even without a robots.txt comment.

<url>
  <loc>https://meridiansupply.example.com/agents</loc>
  <changefreq>monthly</changefreq>
  <priority>0.5</priority>
</url>
<url>
  <loc>https://meridiansupply.example.com/agents.json</loc>
  <changefreq>monthly</changefreq>
  <priority>0.5</priority>
</url>

agents.json discovery_cross_links Field

Include this field in your /agents.json. This closes the loop — an agent that starts at /agents.json can immediately navigate to the content map and the bot policy without additional discovery passes.

"discovery_cross_links": {
  "robots_txt": "https://meridiansupply.example.com/robots.txt",
  "sitemap_xml": "https://meridiansupply.example.com/sitemap.xml",
  "llms_txt": "https://meridiansupply.example.com/llms.txt"
}

Declaring your MCP server in the capability manifest.

If you operate an MCP server, the /agents.json manifest is the right place to declare it. For the full MCP protocol primer — JSON-RPC envelope, tool schemas, initialize handshake — see the MCP spoke. This section covers how to advertise your MCP server in the manifest and the current state of the /.well-known/mcp discovery discussion.

MCP Background

The Model Context Protocol (MCP), introduced by Anthropic in November 2024, is a JSON-RPC 2.0-based protocol that lets AI agents discover and invoke external tools through a standardized interface. MCP servers expose three primitive types: Resources (data and context), Prompts (templated workflows), and Tools (callable functions). The current specification is published at modelcontextprotocol.io (2025-03-26 revision — re-verify before launch).

Transport Options

For a merchant deploying an agent-accessible MCP server, Streamable HTTP is the correct transport. The older HTTP+SSE-only transport is deprecated as of the 2024-11-05 spec version.

Full MCP Declaration in agents.json

All data uses the hypothetical meridiansupply.example.com domain:

"mcp": {
  "server_url": "https://mcp.meridiansupply.example.com",
  "transport": "streamable-http",
  "protocol_version": "2025-03-26",
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": true,
    "sampling": false
  },
  "tool_listing_endpoint": "https://mcp.meridiansupply.example.com/tools/list",
  "well_known_mcp": "https://mcp.meridiansupply.example.com/.well-known/mcp",
  "auth_required": true,
  "auth_reference": "https://auth.meridiansupply.example.com/.well-known/oauth-authorization-server",
  "notes": "Connect with any MCP 2025-03-26 compatible client. Streamable HTTP transport. OAuth 2.1 + PKCE required."
}

Capability Negotiation

MCP clients and servers negotiate capabilities during the initialize handshake. The client sends its supported capabilities; the server responds with its own. The manifest declaration above tells an agent before connecting that this server supports tools, resources, and prompts — so the agent can pre-plan its interaction strategy without first opening a connection.

The /.well-known/mcp Discussion (re-verify before launch)

The MCP community is actively debating a /.well-known/mcp discovery endpoint (GitHub discussion #1147 on the modelcontextprotocol organization). Two competing proposals exist as of mid-2026:

• SEP-1649: Server card at /.well-known/mcp/server-card.json — focused on server metadata and capabilities.
• SEP-1960: Discovery manifest at /.well-known/mcp — focused on endpoint enumeration and auth.

Neither is in the official MCP specification (2025-03-26 revision). Publish your MCP URL in /agents.json now. When the community settles on a standard, add the /.well-known/mcp endpoint as a secondary discovery path. Do not rely on /.well-known/mcp alone — no shipping agent runtime currently probes it by default.

The spec chain: OAuth 2.1 + PKCE + RFC 8414 + RFC 7591 + RFC 8693.

The auth section of your manifest is the most technically dense part. This section explains the spec chain that governs it, what each flow means in the context of agent commerce, and shows a complete production-pattern JSON example. All example data uses the hypothetical meridiansupply.example.com domain.

The Spec Chain

Authorization Code with PKCE — for an Agent Buyer

The authorization code flow with PKCE is the correct pattern when a human user is involved — the agent acts on behalf of an authenticated customer. Flow:

1. Agent generates a code_verifier (random string) and computes code_challenge = BASE64URL(SHA256(code_verifier)).
2. Agent opens the authorization URL with response_type=code&code_challenge=<challenge>&code_challenge_method=S256.
3. User logs in and approves the requested scopes.
4. Auth server redirects back with an authorization code.
5. Agent exchanges the code for an access token at the token endpoint, including the code_verifier.
6. Agent uses the access token in Authorization: Bearer <token> for all MCP and API calls.

Client Credentials — for an Operator Agent

The client credentials flow is correct for agent-to-agent or operator-side automation where there is no human in the loop. A merchant's back-office agent (e.g., "refund all delayed orders from Region X") uses client credentials to authenticate directly without a user authorization step. Scope the credentials tightly — never grant checkout or order write scopes to a machine-only client unless the scope is strictly needed.

Full Auth JSON Example (RFC 8414-aligned, for your agents.json)

"auth": {
  "type": "oauth2",
  "flows_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "pkce_required": true,
  "pkce_methods": ["S256"],
  "authorization_server_metadata": "https://auth.meridiansupply.example.com/.well-known/oauth-authorization-server",
  "authorize_url": "https://auth.meridiansupply.example.com/authorize",
  "token_url": "https://auth.meridiansupply.example.com/token",
  "registration_endpoint": "https://auth.meridiansupply.example.com/register",
  "revocation_endpoint": "https://auth.meridiansupply.example.com/revoke",
  "scopes_available": [
    "products:read",
    "inventory:read",
    "pricing:read",
    "orders:read",
    "orders:write",
    "returns:write",
    "checkout:initiate",
    "webhooks:subscribe"
  ],
  "default_token_lifetime_seconds": 3600,
  "refresh_token_supported": true,
  "dynamic_client_registration": true,
  "agent_identity_requirements": "Token requests for orders:write and checkout:initiate must include a signed JWT client assertion per RFC 7521 Section 4.2.",
  "api_key_acquisition": "https://meridiansupply.example.com/developers/api-keys",
  "token_exchange_supported": false
}

The Corresponding RFC 8414 Document

Agents that read RFC 8414 can reconstruct all endpoint URLs from a single /.well-known/oauth-authorization-server fetch. Your /agents.json should point to it; agents should prefer the RFC 8414 document over any hardcoded URLs in the manifest. The RFC 8414 document that lives at /.well-known/oauth-authorization-server on your auth server:

{
  "issuer": "https://auth.meridiansupply.example.com",
  "authorization_endpoint": "https://auth.meridiansupply.example.com/authorize",
  "token_endpoint": "https://auth.meridiansupply.example.com/token",
  "registration_endpoint": "https://auth.meridiansupply.example.com/register",
  "revocation_endpoint": "https://auth.meridiansupply.example.com/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": [
    "products:read",
    "inventory:read",
    "pricing:read",
    "orders:read",
    "orders:write",
    "returns:write",
    "checkout:initiate",
    "webhooks:subscribe"
  ],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post", "private_key_jwt"],
  "service_documentation": "https://meridiansupply.example.com/developers"
}

30DayPivot.com has NOT yet shipped its own /agents.json.

30daypivot.com is the publication behind this article and the AgentMall content cluster it belongs to. We are building our own /agents.json — and we have not shipped it yet.

When we publish it, it will live at https://30daypivot.com/agents.json (and mirrored at /.well-known/agent.json). It will declare our content capabilities (article search, category browsing, topic feed subscription), link to our llms.txt, and reference our sitemap. We will update robots.txt with the # AgentManifest: comment the day it goes live.

Until then, this article is the spec we are following. Every field in the examples above maps to a decision we have made for our own manifest. If you implement /agents.json using this guide before we ship ours, you are ahead of us — which is the right outcome for a publication that teaches merchants to do things first. Watch this page for the live link when it ships.

Eight ways /agents.json breaks in production.

1. Marketing copy on /agents

Mistake: Writing a human brand pitch at the /agents URL — "We're excited to welcome AI agents to our platform!" with no machine-readable data. Fix: Split the URL. Serve human prose at /agents/index.html. Serve the JSON manifest at /agents.json (or /.well-known/agent.json). Link between them with a <link rel="agent-manifest"> element. The machine file has zero marketing copy.

2. Forgetting to link from robots.txt

Mistake: Publishing /agents.json but not telling anything about it in robots.txt. Agents that start discovery with robots.txt — which many do, following the bot convention — never find your manifest. Fix: Add this comment to robots.txt: # AgentManifest: https://yoursite.com/agents.json. Place it near the top, before the first User-agent: block.

3. JSON manifest that 404s

Mistake: Deploying the manifest at a URL you reference but haven't actually made live. Agents that try to fetch it get a 404, cache the miss, and stop probing. Fix: Deploy the JSON file as a static asset at the declared path before publishing any cross-references. Test with curl -I https://yoursite.com/agents.json and confirm HTTP 200 with Content-Type: application/json. If you are on a CDN or static host, ensure the file is in the public root and not blocked by a redirector.

4. OAuth declarations that don't match actual flows

Mistake: The /agents.json says you support client_credentials, but your authorization server has no client credentials endpoint configured. Or you declare pkce_required: true but your token endpoint accepts code exchanges without code_verifier. Fix: Fetch your RFC 8414 document from your actual auth server (curl https://auth.yoursite.com/.well-known/oauth-authorization-server) and copy the values from there into /agents.json. Validate that every scope in scopes_available is a scope your auth server actually grants.

5. Sandbox endpoints with no real test data

Mistake: Declaring a sandbox URL but providing no test SKUs, no test orders, no seeded data. Agents trying to validate their integration against the sandbox get empty results or errors and cannot confirm their tool calls work. Fix: Seed the sandbox with at least: one in-stock product, one out-of-stock product, one fulfilled order (eligible for status check), and one return-eligible order. Document the exact identifiers in the test_data section. A sandbox without seeded data is a 404 with extra steps.

6. No identity or contact information

Mistake: Publishing a capability manifest with only technical fields and no identity section. Agents have no way to route escalations, and operators reviewing agent traffic have no attribution anchor. Fix: Always include agent_contact, abuse_contact, and operator_name. These fields cost you nothing and prevent entire categories of silent failures when something goes wrong (rate limit breach, malformed request, abuse incident).

7. Stale capability list

Mistake: Publishing the manifest once and never updating it. Six months later, you've added a get_loyalty_points capability and deprecated subscribe_to_newsletter, but the manifest still reflects the original state. Agents using the manifest make incorrect assumptions. Fix: Version the manifest with manifest_version and last_updated. Treat the manifest as a versioned artifact — update it whenever you add, remove, or change a capability. Set Cache-Control: public, max-age=86400 so agents re-fetch it regularly.

8. Return and shipping policies as human-only HTML

Mistake: Linking return_policy to a human-readable HTML page with policy text buried in paragraphs. An agent trying to advise a user on whether a return is eligible must parse prose to find "30 days from delivery." Fix: Publish machine-readable JSON versions of your core policies. The return policy JSON should have explicit fields like return_window_days: 30, restocking_fee_percent: 0, eligible_conditions: ["unused", "defective"]. Link the JSON from the manifest. The HTML version stays for human browsing.

Frequently asked questions.

Five steps to a live /agents.json.

Each step mirrors the HowTo JSON-LD at the top of this page word for word. Execute in order. The whole sequence can be completed in a focused afternoon once your API and auth infrastructure is in place.

Step 1 — Inventory the Capabilities and Endpoints Agents Need

Before writing a single line of JSON, map what agents can actually do on your site. Walk your own API or MCP server and list every callable action. For each action, note: what inputs it takes, what it returns, whether it requires authentication, and whether it has write side effects. This inventory is your capabilities array. Do not include actions that are not implemented — a capability list that advertises initiate_checkout when checkout is not agent-accessible will cause silent failures and bad agent behavior. At the same time, compile your endpoint inventory: MCP server URL (if applicable), REST base URL, GraphQL URL (if applicable), OpenAPI spec URL, and your auth server's RFC 8414 URL. If you do not have an OpenAPI spec, generate one from your existing API before publishing the manifest.

Step 2 — Author /agents.json with Required Fields

Start from the full JSON template in this article. Fill in the identity, capabilities, endpoints, and auth sections first — these are the minimum viable manifest. Add sandbox, policies, receipts, and sample_queries before going to production. Use real values throughout. Copy the auth endpoint URLs from your live authorization server's RFC 8414 document (curl https://auth.yoursite.com/.well-known/oauth-authorization-server) and copy the values from there into /agents.json. Never write auth metadata by hand — derive it from the live server. Validate that every scope in scopes_available is a scope your auth server actually grants. Set Content-Type: application/json and Access-Control-Allow-Origin: * in the response headers. Set Cache-Control: public, max-age=86400. Validate the JSON with jq . agents.json before deploying.

Step 3 — Cross-Link from robots.txt, llms.txt, and sitemap.xml

Add # AgentManifest: https://yoursite.com/agents.json to robots.txt. Add a mention of the manifest URL in the blockquote of llms.txt. Add the /agents and /agents.json URLs to sitemap.xml. Inside agents.json itself, add the discovery_cross_links section pointing to robots.txt, sitemap.xml, and llms.txt. This four-way cross-reference ensures that an agent entering your site at any of the four standard discovery points can reach all the others within one or two hops.

Step 4 — Stand Up a Sandbox and Seed Sample Queries

Deploy your sandbox endpoint before you link to it. Seed it with the test data documented in the manifest: specific product SKUs, at least one fulfillable test order, at least one return-eligible order. Confirm that the sandbox returns realistic responses — if check_inventory returns {"quantity": 9999} for every test SKU, agent developers will not trust the results. Write at least four sample queries in the sample_queries field — one for each of read-only product/inventory access, one for a write operation (initiate checkout or return), and one for a subscription (restock webhook). Test each sample query against the sandbox manually before publishing.

Step 5 — Verify Discovery with curl and a Real MCP Client

Run the following verification checklist before calling the manifest production-ready: confirm the manifest is reachable and valid JSON (curl -s -H "Accept: application/json" https://yoursite.com/agents.json | jq .); confirm the RFC 8414 auth metadata is reachable; confirm robots.txt contains the AgentManifest comment; confirm sitemap.xml includes /agents; confirm CORS headers are set correctly. Then connect a real MCP client (Claude Desktop, Claude Code, or the mcp CLI) to your declared MCP server URL. Issue each sample query from the manifest. Confirm that the tool calls complete successfully and that the responses match the documented return shapes. Fix any gaps before the manifest goes live.

# 1. Confirm the manifest is reachable and valid JSON
curl -s -H "Accept: application/json" https://yoursite.com/agents.json | jq .

# 2. Confirm the RFC 8414 auth metadata is reachable
curl -s https://auth.yoursite.com/.well-known/oauth-authorization-server | jq .

# 3. Confirm robots.txt contains the AgentManifest comment
curl -s https://yoursite.com/robots.txt | grep AgentManifest

# 4. Confirm sitemap.xml includes /agents
curl -s https://yoursite.com/sitemap.xml | grep agents

# 5. Confirm CORS headers are set correctly
curl -sI https://yoursite.com/agents.json | grep -i "access-control\|content-type"

Next stops in the AgentMall guide.

Platform Siblings

The discovery stack applies across every platform. Once your /agents.json is live, ensure your platform's MCP endpoint and checkout flow are wired correctly:

• Shopify Agent-Ready Retrofit — native /api/mcp, UCP catalog enrollment, Liquid schema extension
• WooCommerce Agent-Ready Retrofit — WooCommerce REST API, custom MCP wrapper, Schema.org via Yoast
• BigCommerce Agent-Ready Retrofit — Catalog API, Storefront API, MCP server on Catalyst
• Headless Commerce Agent-Ready Retrofit — Sanity, Contentful, Strapi — custom MCP layer, composable stack
• Etsy Agent-Ready Retrofit — Etsy Open API v3, listing optimization, agent discovery within marketplace constraints

Related Spokes

• Agent SEO 2026 — the ranking signals that determine whether your products get cited and recommended
• API Endpoint — The Eight-Endpoint Surface — the REST/GraphQL surface your /agents.json points to
• UCP — Universal Commerce Protocol — the checkout state machine that agent buyers execute
• Product Data — The 20-Field MVP — the Schema.org block that feeds agent SEO and structured discovery
• The Agent Commerce Market — TAM and channel mix for sizing the opportunity
• Picks & Shovels — cross-platform tools for schema validation, MCP scaffolding, and monitoring