Skip to content
legibility

MCP server + x402

Legibility serves its product tools over the Model Context Protocol. Discovery is free. A tool call is paid with a Legibility API key, or per call in USDC over x402 on Base Sepolia, a testnet.

Endpoint

POST https://legibility.io/api/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

JSON-RPC 2.0 over HTTP POST. initialize, tools/list and ping need no key and cost nothing.

Tools

This is the list tools/list returns. Each tool also carries an input schema, an output schema and read-only annotations.

  • read_product (Read a product)

    Read one product page URL or GTIN barcode into a typed product with per-field and overall calibrated confidence, a price band, the extraction method and the cost of the call. Trusted coverage is structured data: product pages that serve schema.org Product JSON-LD, Shopify stores and GTIN barcodes, plus OpenGraph pages admitted through a verified prior. Below the 0.7 trust gate, or when a page is not safe to read (blocked, a 404, not a product), it returns product: null with a low confidence instead of a guess, and that read is not charged. Pay with a Legibility API key, or per call in USDC over x402 on Base Sepolia (testnet).

  • resolve_product (Resolve a product name)

    Resolve a product name someone typed into one typed product: a web search finds candidate pages, then the best candidate is read as read_product reads a page, in the same call. Trusted coverage is structured data: product pages that serve schema.org Product JSON-LD, Shopify stores and GTIN barcodes, plus OpenGraph pages admitted through a verified prior. Below the 0.7 trust gate, or when a page is not safe to read (blocked, a 404, not a product), it returns product: null with a low confidence instead of a guess, and that read is not charged. When search is unavailable or no candidate can be read safely, it also returns product: null. Pay with a Legibility API key, or per call in USDC over x402 on Base Sepolia (testnet).

compare_products and brief_product are available over REST only, not yet on the MCP tool list.

Authenticate with an API key

Create a key in the dashboard at https://legibility.io. Keys start with lgk_ and are shown once. Send it as a bearer token on every request. A keyed call is rate limited and counted against your plan, and a read that returns no product is never charged.

{
  "mcpServers": {
    "legibility": {
      "url": "https://legibility.io/api/mcp",
      "headers": { "Authorization": "Bearer lgk_your_key" }
    }
  }
}

Pay per call (x402)

A tools/call with no valid key and no X-PAYMENT header returns 402 Payment Required with the payment requirements. Payments settle on Base Sepolia (testnet), 0.01 test USDC a call. No mainnet settlement yet.

402 Payment Required
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "10000",
    "asset": "<USDC contract on Base Sepolia>",
    "payTo": "<the Legibility recipient>"
  }]
}

Manifest

The discovery document, built from the same tool list: https://legibility.io/.well-known/mcp.json.