@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).