Nagora MCP server

The official MCP server for nagora.shop, the P2P marketplace where everything settles in Nano (XNO).

It gives any MCP client (Claude Desktop, Claude Code, or your own agent runtime) tools to search listings, place escrow-protected purchases, track orders, and pull signed receipts. Your AI assistant can shop for you, and escrow protects you while it does: funds are held in a per-order Nano account and only released to the seller after delivery is confirmed.

Tools

Tool	Auth	What it does
search_listings	none	Full-text search over active listings
get_listing	none	Full listing detail: variants, delivery options, Nano pricing
register_agent	none	Create an agent + API key in one call, no account needed; key is stored locally
whoami	API key	Verify the key; see spending caps and webhook secret
create_purchase	API key	Place an order; returns the escrow deposit address and amount
get_order	API key	Poll order and escrow status, tracking, receipt ID
confirm_delivery	API key	Confirm arrival and release escrow to the seller
cancel_order	API key	Cancel an order that has not been funded yet
get_receipt	API key	Fetch the KMS-signed receipt with the on-chain payout block

Setup

Zero-install alternative: Nagora also hosts these same tools as a remote MCP server. claude mcp add --transport http nagora https://api.nagora.shop/mcp and you are done. The trade-off: the hosted server cannot store your key locally, so register_agent returns it once and you pass it as the apiKey tool argument or pin it with --header "Authorization: Bearer nag_agt_...". This local package keeps the key in ~/.nagora/credentials.json for you instead.

Claude Code

claude mcp add nagora -- npx -y @nagora/mcp

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "nagora": {
      "command": "npx",
      "args": ["-y", "@nagora/mcp"]
    }
  }
}

From source (instead of npx)

cd nagora-mcp
npm install
npm run build
claude mcp add nagora -- node /path/to/nagora-mcp/dist/index.js

Let the agent register itself

That's the whole setup. No Nagora account, no key to copy. The first time your assistant needs to buy something, it calls register_agent with a name and a refund Nano address; the API key comes back once and is saved to ~/.nagora/credentials.json (mode 600). Every other tool picks it up automatically from then on.

Self-registered keys get conservative default spending caps (currently 25 XNO per transaction, 100 XNO per day), enforced server-side. Want higher caps, multiple keys, or a dashboard? Create an account at nagora.shop and manage agents under Settings → Agents; keys minted there work the same way via NAGORA_API_KEY.

Configuration

Variable	Default	Notes
NAGORA_API_KEY	unset	Optional. Overrides the stored credential from register_agent
NAGORA_API_URL	https://api.nagora.shop	Point at http://localhost:5004 for local dev

How a purchase flows

1. search_listings / get_listing: find the item, note the Nano total.
2. create_purchase: places the order. The response contains a depositAddress (a per-order escrow account on the Nano network) and amountNano.
3. Fund the escrow: send exactly amountNano to depositAddress from the agent's own Nano wallet. This server deliberately holds no keys and moves no funds; pair it with a wallet tool such as xno-mcp, or fund it manually. Nano transfers are feeless and settle in under a second.
4. The order moves to AwaitingShipment automatically when funds land. The seller ships and adds tracking.
5. get_order (or webhooks, see below) to watch for Shipped.
6. confirm_delivery once the goods arrive: escrow releases the funds to the seller on-chain.
7. get_receipt: a signed, independently verifiable proof of the whole transaction, including the payout block hash.

If the seller never ships, the escrow auto-cancel timer refunds the buyer. If something is wrong with the order, open a dispute from the website; a human reviews it.

Webhooks (optional)

Instead of polling get_order, register a callbackUrl on your agent (Settings → Agents). Nagora signs every webhook with HMAC-SHA256: compute HMAC-SHA256("{X-Nagora-Timestamp}.{raw_body}", webhookSecret) and compare it against X-Nagora-Signature: sha256=<hex>. The webhookSecret comes from whoami.

Events: order.funded, order.shipped, and friends fire as the order progresses.

Safety model

• The server is stateless and keyless: it cannot spend Nano, only request orders that you then fund (or don't).
• Spending caps are enforced server-side per API key; a runaway agent hits a 429, not your wallet.
• Escrow means an agent mistake is recoverable: unfunded orders can be cancelled, funded orders are protected until you confirm delivery.
• Revoke a key at any time from Settings → Agents; revocation takes effect within 60 seconds.