Blueprint Developer & Agent Documentation

Programmatic access to the Blueprint store at blueprint.bryanjohnson.com. This storefront runs on Shopify and implements the Universal Commerce Protocol (UCP) for agent-driven commerce.

Discovery

Fetch the UCP merchant profile — supported versions, service endpoints, capabilities, and payment handlers:

GET https://blueprint.bryanjohnson.com/.well-known/ucp

MCP Endpoint

Model Context Protocol endpoint for agent transactions. Use tools/list to discover available tools and their schemas.

POST https://blueprint.bryanjohnson.com/api/ucp/mcp
Content-Type: application/json

The UCP profile advertises this endpoint on blueprint-bryanjohnson.myshopify.com. Both hosts serve it; prefer whichever /.well-known/ucp returns.

Supported UCP versions

2026-04-08 (latest stable)
2026-01-23

Agent flow

Discover — GET /.well-known/ucp
Search — search_catalog
Cart — create_cart
Checkout — create_checkout
Fulfill — update_checkout (shipping address and method)
Complete — complete_checkout (requires buyer approval)

Read-Only Endpoints (no authentication)

Catalog data requires no credentials:

Endpoint	Returns
`GET /products.json`	All products (`?limit=250` returns the full catalog)
`GET /products/{handle}.json`	Product detail
`GET /collections/{handle}/products.json`	Collection products
`GET /sitemap.xml`	URL index

/search and /collections/{handle} return HTML, not JSON. For programmatic search use search_catalog over the MCP endpoint above. The page parameter is unreliable on this storefront — prefer a single ?limit=250 request.

These catalog endpoints send no Access-Control-Allow-Origin header, so a browser-resident agent cannot read them cross-origin — call them server-side or through a proxy. The MCP endpoint and the OpenAPI document below are both served with Access-Control-Allow-Origin: *.

An unknown collection handle returns 200 with an empty products array rather than a 404. Check the array length, not the status code.

Machine-readable API description: /openapi.json (OpenAPI 3.1). Browser-based clients should fetch the versioned file directly — /cdn/shop/files/openapi-2026-08-27.json — as the short URL is a redirect and redirects are not CORS-transparent.

Authentication and Scopes

Catalog reads need no authentication. Customer-account access uses Shopify's authorization server:

GET https://blueprint.bryanjohnson.com/.well-known/oauth-authorization-server

Available scopes are openid, email, customer-account-api:full, and customer-account-mcp-api:full. Note that the data-granting scopes are full-access only — Shopify does not currently offer read-only variants.

Requesting Markdown

Send Accept: text/markdown, */* when requesting pages from this domain. Omitting */* causes the platform to echo the requested type into Content-Type while still returning HTML — a confirmed Shopify storefront issue, tracked upstream.

Agent Instruction Files

/agents.md — canonical agent instructions
/llms.txt — mirror
/llms-full.txt — mirror (currently byte-identical to /llms.txt, not a fuller corpus)
/robots.txt — crawler directives

Rules for Agents

Checkout requires explicit buyer approval. Do not complete payment without contemporaneous buyer consent. If you cannot obtain it at the moment of payment, route through the Shop skill and Shop Pay.
Respect rate limits. The MCP endpoint is rate-limited per IP. Back off on 429 responses.
Pass buyer context. Include context.address_country and context.currency for accurate pricing and availability.