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