nagora-mcp

# Nagora MCP server

The official [MCP](https://modelcontextprotocol.io) server for [nagora.shop](https://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

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

### Claude Desktop

In `claude_desktop_config.json`:

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

### From source (instead of npx)

```bash
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](https://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.