API & MCP documentation

Check any domain for Universal Commerce Protocol support, find the stores an agent can actually transact with and search their live catalogues, then shop at the store directly — from the independent record that re-checks every verified store daily. Read-only and keyless.

Quickstart

Add the UCP Checker MCP server to any MCP-capable agent. It gets check-domain, list-stores, search-all and five more tools in its tray; resolving a store to buy from is four calls.

claude mcp add --transport http ucp-checker https://ucpchecker.com/mcp

{
    "mcpServers": {
        "ucp-checker": {
            "url": "https://ucpchecker.com/mcp"
        }
    }
}

{
    "mcpServers": {
        "ucp-checker": {
            "type": "streamable-http",
            "url": "https://ucpchecker.com/mcp"
        }
    }
}

https://ucpchecker.com/mcp

{
    "servers": {
        "ucp-checker": {
            "type": "http",
            "url": "https://ucpchecker.com/mcp"
        }
    }
}

That is the whole setup. What the server exposes is under MCP server; no MCP client, use the REST API or ARD search.

CLI

No agent, no MCP client — just a terminal or a CI job. ucp-check is a zero-dependency Node client over the REST API below: it renders the verdict the API returns and turns it into an exit code. It never scores locally, so a check from CI says exactly what the status page says.

npx ucp-check your-store.com

--cached reads the last observed state without crawling (use it on every push; run the live check on deploy), --json prints the response as served, --quiet is exit-code only. Source and issues: github.com/ucpchecker/ucp-check · npm.

MCP server

One streamable-HTTP server at https://ucpchecker.com/mcp. It exposes the 8 tools documented below, read straight from the server class so this page cannot drift from what it serves. Read-only tools are open at every tier; the cart tools are for signed or token callers once enforcement is on. The server also publishes a machine-readable card at /.well-known/mcp/server-card.json.

The resolution flow — list-stores (or search-all) → search-catalog → get-product-details → search-policies, then discover-store to see what the merchant itself exposes. There is no server-side session. UCP Checker is read-only: it resolves and measures, it never carts, checks out or takes payment — you transact with the merchant.

Authentication & rate limits

Every read endpoint is open: no API key, no signup. Limits are per IP and per tier:

REST: POST /api/v1/check is 30/min and 200/day per IP (it crawls); other endpoints 60/min and 1,000/day. ARD endpoints share the REST limiter. Over the limit you get 429 with Retry-After. Our own outbound requests are signed too — verify them against /.well-known/http-message-signatures-directory.

Guide — build a shopping agent

The minimum viable agent is six steps. With the MCP server connected, steps 1–5 are single tool calls; without it, the same flow works against any store's own UCP profile and MCP endpoint. The long-form version, with code, is at /agents.

To test the whole journey against a live store with a real model — every tool call recorded — use the UCP Playground.

Guide — methodology & the UCP score

Every verified store is re-checked daily from the outside in: we fetch its profile as an agent would, validate it against the current spec, read its bot policies and surface signals, and record what we observed. The score summarises that record. The full method — crawler behaviour, response classification, validation rules, refresh schedule — is on the methodology page; this is the part you need to read a number.

score = discovery × 0.30 + conformance × 0.40 + capabilities × 0.30 , rounded to the nearest integer. A blocked or unreachable store scores 0 on discovery; an undetected profile caps it.

The score is a summary of observed conformance, not a ranking and not a trust rating. In ARD results it travels as metadata.ucpScore, deliberately separate from the relevance score.

Guide — score model versioning

A reading is only useful if today's number means the same thing as last quarter's. So the score model is versioned, history is never rescored, and every number says which model produced it. Drift is not forbidden — unlabelled drift is.

MAJOR — a stable field is removed, renamed or changes meaning. MINOR — anything additive, including check-catalogue membership. PATCH — documentation or spec-only corrections. Stable within a major: domain, status, score, grade, category_scores keys, check ids, model_version, contract_version.

Never rescore history. A point in the series reflects the model in force when it was observed; backfilling today's model onto old dates would assert scores merchants never had. Announce every model change on the blog and the methodology page before it ships. Gate CI on check ids or a threshold, not on "all required checks pass" — the required set can grow on a minor.

Check & resolve

Read catalogs & policies

Discovery — Agentic Resource Discovery

UCP Checker is an ARD v0.91 discovery service — the federated standard agents use to ask "what's available for this task?" before invoking anything. Every result is a verified storefront as a standard catalogue entry: identifier (urn:air:{domain}:ucp:storefront), url (the store's /.well-known/ucp), capabilities, metadata (category, platform, grade, ucpScore, mcpEndpoint) and a trustManifest whose attestations link the store's public conformance record. Ask for type: ["application/mcp-server-card+json"] and stores with an MCP endpoint come back as inline server cards.

curl -s -X POST https://ucpchecker.com/ard/search \
  -H 'Content-Type: application/json' \
  -d '{"query": {"text": "running shoes",
              "filter": {"metadata.platform": ["shopify"]}},
       "federation": "none", "pageSize": 5}'

curl -s -X POST https://ucpchecker.com/ard/explore \
  -H 'Content-Type: application/json' \
  -d '{"resultType": {"facets": [{"field": "metadata.category", "limit": 10},
                                {"field": "metadata.platform"}]}}'

curl -s "https://ucpchecker.com/ard/agents?pageSize=20&orderBy=updatedAt%20DESC"

REST API

The same record over plain HTTP. All responses are JSON; the request and response shapes are published as JSON Schema at /api/v1/schema.

Observed, not asserted. Every record carries two timestamps: observed_at — when we last actually saw the store (any status) — and attempted_at — when we last tried. outcome says what the latest attempt told us; only observed refreshes status. When a store's edge rate-limits our crawler the attempt is recorded, observed is false, and the record you get is the last observation, not a new verdict. Treat observed_at as the freshness of the data.

curl -s -X POST https://ucpchecker.com/api/v1/check \
  -H 'Content-Type: application/json' \
  -d '{"domain": "allbirds.com"}'

curl -s https://ucpchecker.com/api/v1/status/allbirds.com

curl -s https://ucpchecker.com/api/v1/schema

Skills

Self-contained instruction documents for coding agents, served live at /.well-known/agent-skills/index.json (with sha256 digests) so the current spec version never bakes into an agent's memory. Paste the URL into your agent, or fetch it over MCP as a resource.

https://ucpchecker.com/.well-known/agent-skills/ucp-agent-ready/SKILL.md

https://ucpchecker.com/.well-known/agent-skills/ucp-checker/SKILL.md

Well-known files

Everything an agent needs to discover and verify this server without being told about it.

Errors

ARD errors follow the spec's error object — a top-level errorCode and message — and every failure under /ard, including the ones the server raises itself, is JSON: { "errorCode": "INVALID_ARGUMENT", "message": "…", "error": { "code": "INVALID_ARGUMENT", "message": "…" } }. The nested error object is the shape this endpoint shipped with; it stays for existing clients, and new ones should read errorCode.

Versioning

The API contract is v1.0.0. The REST response envelope and the MCP tool names are stable within a major version; new tools and new optional fields are additive. The UCP score model is versioned separately from the API — a score change is a model change, never a silent one, and is announced on the blog and in the methodology. Nothing is removed without notice.

Where it's listed