@giftcardshop/mcp

MCP server that lets AI agents browse the giftcardshop catalog and buy gift cards with Lightning - no account, no signup. The agent pays a Lightning invoice and receives a single-view reveal link with the code.

Read tools work against the live public API with no key. create_order is early access: it needs the shared GCS_INTERNAL_SECRET (request one at https://giftcardshop.org/contact); without it the read tools still work and create_order reports that it is not configured.

Tools

| Tool | Kind | Backed by | |------|------|-----------| | list_brands | read | GET /v1/brands | | search_products | read | GET /v1/products | | get_product | read | GET /v1/products/:id (variants + denominations) | | get_order_status | read | GET /v1/orders/:id (payment state + reveal availability) | | create_order | write | POST /internal/agent-orders (HMAC) -> Lightning invoice |

Read tools pass the API JSON through verbatim. create_order returns { orderId, invoiceId, invoiceUrl, bolt11?, sats?, total, currency, expiresAt }.

Run

# read-only (browsing works, create_order reports "not configured")
npx @giftcardshop/mcp

# with checkout enabled
GCS_INTERNAL_SECRET=<64-hex> npx @giftcardshop/mcp

Claude Desktop / any MCP client (stdio):

{
  "mcpServers": {
    "giftcardshop": {
      "command": "npx",
      "args": ["-y", "@giftcardshop/mcp"],
      "env": { "GCS_INTERNAL_SECRET": "<64-hex>" }
    }
  }
}

Config

| Env | Default | Purpose | |-----|---------|---------| | GCS_API_BASE | https://api.giftcardshop.org | public API base | | GCS_INTERNAL_SECRET | (unset) | 64-hex HMAC secret; enables create_order. Unset = read-only. |

Checkout (create_order)

create_order POSTs to POST /internal/agent-orders, HMAC-signed with GCS_INTERNAL_SECRET (header x-internal-sig), and returns a Lightning invoice. Pay it, then poll get_order_status for the single-view reveal link. No Nostr identity and no partner account required.

Roadmap

• L402 (Lightning HTTP 402) so an agent pays per-call without a human step.
• A hosted remote MCP over HTTP, so there is nothing to install.
• A btcrecharge MCP for mobile top-ups (same shape).