generated: '2026-08-16'
method: probed
source: https://www.flyingembers.com/api/ucp/mcp
docs: https://www.flyingembers.com/llms.txt
scope: >-
  Cross-cutting request/response semantics of the Flying Embers agent surface, derived
  from the live UCP/MCP tools/list JSON Schemas and the merchant's published /llms.txt,
  /agents.md and /robots.txt.

authentication:
  style: anonymous
  detail: >-
    The UCP shopping MCP endpoint accepts anonymous JSON-RPC. Customer-account access uses
    OIDC authorization-code + PKCE against a store-scoped issuer.
  see: authentication/flying-embers-authentication.yml

idempotency:
  supported: true
  mechanism: request-metadata field
  field: meta.idempotency-key
  type: string
  scope: complete_checkout
  required: true
  retention: not published
  evidence: >-
    complete_checkout declares "idempotency-key" in meta.properties with description
    "An idempotency key for completing the checkout." and lists it in meta.required
    alongside ucp-agent. Verified in the live tools/list response, 2026-08-16.
  note: >-
    Idempotency is enforced only on the one irreversible operation (payment completion).
    Cart and checkout mutations are not idempotency-keyed.
  source: mcp/flying-embers-mcp-tools-list.json

pagination:
  style: cursor
  applies_to: [search_catalog]
  request:
    container: catalog.pagination
    params:
      - name: cursor
        type: string
        description: Pagination cursor returned by the previous page.
      - name: limit
        type: integer
        default: 10
        description: Number of results to return.
  response:
    field: pagination.cursor
    detail: >-
      "Results are paginated, with initial results limited to improve experience. Use the
      pagination.cursor from the response to fetch additional pages when users request
      more results."

money:
  representation: integer minor units + currency code
  example: '{"amount": 600, "currency": "USD"} is $6.00'
  currency_format: ISO 4217
  note: Applies to every price field in every catalog, cart, checkout and order response.

localization:
  request_context: catalog.context
  fields:
    - {name: address_country, format: ISO 3166-1 alpha-2}
    - {name: address_region}
    - {name: postal_code}
    - {name: language, format: IETF BCP 47}
    - {name: currency, format: ISO 4217}
    - {name: intent, description: Buyer intent signal}
  detail: >-
    llms.txt instructs agents to pass context.address_country and context.currency for
    accurate pricing and availability.

agent_identity:
  required: true
  field: meta.ucp-agent.profile
  type: string (uri)
  description: >-
    Every tool call must carry an agent profile URI used for UCP agent discovery. This is
    the surface's caller-identity contract in place of an API key.

request_tracing:
  header: x-request-id
  observed: true
  example_shape: 12304e61-dc79-44c1-b8a4-9fc855cbc3db-1786899402
  note: Returned on the MCP response; observed on an anonymous tools/list, 2026-08-16.

versioning:
  scheme: date
  current: '2026-04-08'
  supported: ['2026-04-08', '2026-01-23']
  response_header: x-shopify-ucp-mcp-api-version
  discovery: https://www.flyingembers.com/.well-known/ucp
  version_pinned_profile: https://www.flyingembers.com/.well-known/ucp/2026-04-08
  see: lifecycle/flying-embers-lifecycle.yml

error_envelope:
  format: JSON-RPC 2.0 error object
  shape: '{"jsonrpc":"2.0","id":<id>,"error":{"code":<int>,"message":<string>,"data":<any>}}'
  note: >-
    No provider-published error registry exists for this surface; the envelope is the
    JSON-RPC 2.0 standard one carried by MCP. HTTP 429 is documented for rate limiting.
  see: errors/flying-embers-problem-types.yml

rate_limit_signaling:
  documented: true
  detail: 'llms.txt: "Respect rate limits. The MCP endpoint is rate-limited per IP. Back off on 429 responses."'
  status_on_exhaustion: 429
  headers_published: false
  see: rate-limits/flying-embers-rate-limits.yml

human_in_the_loop:
  required_for: [complete_checkout]
  rule: >-
    "Checkout requires human approval. Agents must not complete payment without explicit
    buyer consent." Restated in robots.txt: no scripted form fills, browser automation, or
    end-to-end agent flows that finalize payment without an explicit, contemporaneous
    human approval step.
  sources:
    - https://www.flyingembers.com/llms.txt
    - https://www.flyingembers.com/robots.txt

read_only_surface:
  description: Unauthenticated storefront JSON documented by the merchant for read-only agents.
  endpoints:
    - GET /collections/all
    - GET /products/{handle}
    - GET /products/{handle}.json
    - GET /collections/{handle}
    - GET /collections/{handle}/products.json
    - GET /search?q={query}&type=product
    - GET /sitemap.xml
  source: https://www.flyingembers.com/llms.txt
  note: >-
    robots.txt disallows /cart.js and /recommendations/products and directs agents to the
    UCP/MCP endpoints for cart and checkout instead.