# Nacre for agents

Nacre is a privacy router for AI agents on Solana: check a counterparty, shield the float, route value to Zcash, Aleo, Bitcoin and more, and pay for it from the agent's own wallet. Use it as a remote MCP server (nothing to install) or run it locally (adds signing tools).

## Connect

### Option A: remote MCP, nothing to install (read-only)

    claude mcp add --transport http nacre https://nacreshield.xyz/mcp

Any client that supports Streamable HTTP MCP can use `https://nacreshield.xyz/mcp`. Tools: `glass_check`, `pool_depth`, `route_tokens`, `route_quote`, `route_create`, `route_status`. The hosted server never holds keys, so the signing tools below are local only.

### Option B: local server, all tools

    curl -O https://nacreshield.xyz/nacre-mcp.mjs
    claude mcp add nacre -- node nacre-mcp.mjs
    node nacre-mcp.mjs --check      # optional self-test

Needs Node 22 or newer. Use an absolute path to the file if your client does not launch from the same folder.

### Claude Desktop, Cursor, Windsurf, any stdio client

    {
      "mcpServers": {
        "nacre": {
          "command": "node",
          "args": ["/absolute/path/to/nacre-mcp.mjs"],
          "env": { "NACRE_KEYPAIR": "/path/to/agent-keypair.json", "NACRE_MAX_USDC": "250" }
        }
      }
    }

Drop the `env` block for read-only use. On Windows use forward slashes or escaped backslashes.

## Environment (local server)

| Variable | Purpose |
|---|---|
| `NACRE_KEYPAIR` | Path to a Solana keypair JSON. Enables `shield`, `unshield`, `private_balance`, `route_fund`. Use a dedicated agent wallet funded with only what the agent needs. |
| `NACRE_MAX_USDC` | Per-call USD cap on `shield`, `unshield` and `route_fund`. Strongly recommended for autonomous agents. |
| `NACRE_RPC_URL` | Dedicated Solana RPC (Helius, QuickNode, Triton). Without it Nacre fails over between free public endpoints. |
| `NACRE_FEE_RECIPIENT`, `NACRE_FEE_BPS` | Optional route fee (NEAR account, basis points). |

Install the signing dependencies next to the file: `npm install @umbra-privacy/sdk@4.0.0` for shielding, `npm install @solana/web3.js @solana/spl-token` for `route_fund`.

## Tools

| Tool | Where | Moves funds | Use |
|---|---|---|---|
| `glass_check(address)` | both | no | Exposure report for a Solana wallet: first funder, active hours, repeat counterparties, 0-100 score. |
| `pool_depth(depth?)` | both | no | Live Umbra and Privacy Cash activity and hours until a crowd of `depth` forms. |
| `route_tokens(chain?)` | both | no | Chain ids and token symbols reachable through NEAR Intents. |
| `route_quote(from_chain, from_symbol, to_chain, to_symbol, amount)` | both | no | Live quote. |
| `route_create(..., recipient, refund_to?)` | both | no | Returns a deposit address. `refund_to` defaults to the agent wallet on a local server with a keypair. |
| `route_fund(deposit_address)` | local | yes | Sends the quoted SOL or USDC from the agent wallet to a deposit address created by `route_create` in this session. Pays each address once. |
| `route_status(deposit_address)` | both | no | Poll until SUCCESS or REFUNDED. |
| `shield(amount)` | local | yes | USDC into an Umbra encrypted balance. |
| `unshield(amount, to?)` | local | yes | USDC out to any Solana address. |
| `private_balance()` | local | no | Decrypt the shielded USDC balance locally. |

Amounts are decimal strings. Chain ids are lowercase (`sol`, `zec`, `aleo`, `btc`, `eth`, `base`, `arb`, `hood`).

## Typical flow

1. `glass_check` the counterparty, and your own wallet.
2. `pool_depth` to choose how long to wait.
3. `shield` the float. Later `private_balance`, then `unshield` to pay.
4. Another chain: `route_tokens`, `route_quote`, `route_create`, then `route_fund` (or send to the deposit address yourself), then `route_status` until done.

## REST API

Same read-only data over plain HTTP, no key needed. OpenAPI: https://nacreshield.xyz/api/openapi.json

    curl "https://nacreshield.xyz/api/glass-check?address=<solana address>"
    curl "https://nacreshield.xyz/api/pool-depth?depth=128"
    curl "https://nacreshield.xyz/api/routes/tokens?chain=zec"
    curl -X POST https://nacreshield.xyz/api/routes/quote -H 'content-type: application/json' \
      -d '{"from_chain":"sol","from_symbol":"USDC","to_chain":"zec","to_symbol":"ZEC","amount":"5"}'
    curl "https://nacreshield.xyz/api/routes/status?deposit_address=<address>"

`POST /api/routes` creates a route like `route_create`. Errors return `{"error": "..."}` with status 400. Results are cached briefly and rate limited per IP; `503` with `Retry-After` means retry shortly.

## Hosted API keys (optional)

By default the hosted `/mcp` and `/api` endpoints are open and rate limited per IP. To require keys, set `NACRE_API_KEYS=key1,key2` in `.env` and run `docker compose up -d api`. Clients then send `Authorization: Bearer <key>` (or `x-api-key`):

    claude mcp add --transport http nacre https://nacreshield.xyz/mcp --header "Authorization: Bearer <key>"

`/api/health`, `/api/openapi.json` and `/api` stay open. To revoke a key or switch the endpoint off for an agent, remove the key and restart the `api` container. The hosted endpoint is read-only, so there are no spend caps to set there; spend caps (`NACRE_MAX_USDC`) apply to the local server's signing tools.

## Limits

Privacy is risk reduction, not a guarantee. Deposits and withdrawals are public on-chain; privacy comes from what happens between them. The Monero swap through Exolix is custodial while it runs. `glass_check` is a heuristic over the latest 100 transactions. Start small, and read the risk notice at https://nacreshield.xyz/.