BlinkCodes catalog MCP server

BlinkCodes agent interfaces

Machine-readable interfaces for blinkcodes.com — a store selling gift card codes, service top-ups and travel eSIMs, with delivery by email in seconds.

Everything here is a remote, hosted service. There is nothing to install and no server to run: point your client at the URLs below. This repository exists to document those endpoints, pin their schemas, and give working examples.

Discovery documents: /.well-known/agent-card.json, /.well-known/mcp/server-card.json, /.well-known/api-catalog, /.well-known/agent-skills/index.json, /.well-known/acp.json, /.well-known/ucp.

MCP server

Published to the Official MCP Registry as com.blinkcodes/catalog (server.json).

Three tools. The two catalog tools are read-only and free — no key, no account, no payment. The third takes money, and only over x402:

buy_product runs the same rail as POST /api/v1/buy below — verify, reserve, settle, fulfil, in that order — so an agent that found the store through MCP never has to change protocol to complete the purchase. Nothing is charged by the first call, and no wallet is needed to use the other two tools.

Add it to a client that speaks remote MCP:

{
  "mcpServers": {
    "blinkcodes": {
      "type": "http",
      "url": "https://blinkcodes.com/mcp"
    }
  }
}

Full tool schemas and a curl transcript: docs/mcp.md.

A stdio-only client can use the bridge in Dockerfile, which proxies to the same hosted endpoint:

docker build -t blinkcodes-mcp . && docker run -i --rm blinkcodes-mcp

Prefer the direct URL above wherever your client speaks remote MCP — the bridge adds a hop and buys nothing.

Buying, for agents

Payment is USDC on Base over x402. One endpoint, two passes:

priced for that exact item, plus an order block (id, access token, status URL).

1. POST /api/v1/buy with the order body → 402 carrying payment requirements

code, or 202 + status_url if fulfilment outlives the sync window.

1. The identical request with a PAYMENT-SIGNATURE header → 200 with the

// the body, in both passes
{
  "email": "buyer@example.com",
  "product_type": "giftcard",   // giftcard | topup | esim | phone_rental
  "product_id": 187,
  "item_id": 1195,
  "quantity": 1
}

Shortened. The full README is on GitHub.