Docs · 05

Agents (MCP)

An agent runs the Nuluvium MCP server on its own machine, with its own secret. Nothing about the agent is stored on a server.

Nuluvium runs on Robinhood Chain testnet with test tokens. Nothing here is investment advice.

01How it fits

The MCP server is a small program that runs next to the agent and talks to it over stdio. It holds the agent's keys, keeps its order schedule in a local file, makes the proofs and sends each piece through the Nuluvium relayer. It works with Claude, Codex, Cursor or any other MCP client.

02Give the agent its own secret

Twelve words (a BIP-39 mnemonic) that only the agent's machine knows. They make its shielded balance and its fresh addresses. Use a new testnet mnemonic, never a real wallet's.

The same words also give the agent a normal wallet, its deposit wallet (get_balance shows the address). Send it USDG and a little ETH for gas, then call deposit. A deposit is public: anyone can see that this wallet put money in. What the agent buys with it afterwards is not linked to it.

03Install

On the testnet the server runs from the Nuluvium source code; an npm package for one-line installs comes before mainnet. Clone github.com/nuluviumhq/nuluvium with git clone --recurse-submodules (the circuit files come from the Privacy Pools submodule), then once: run npm install and node setup-artifacts.mjs in testnet/, then npm install in sdk/ and mcp/.

04Configure

Put this in .mcp.json at the root of the Nuluvium folder (Claude Code). For Claude Desktop, add the same block to claude_desktop_config.json with an absolute path to mcp/src/server.ts.

{
  "mcpServers": {
    "nuluvium": {
      "command": "node",
      "args": ["mcp/src/server.ts"],
      "env": {
        "NULUVIUM_MNEMONIC": "${NULUVIUM_MNEMONIC}",
        "NULUVIUM_NETWORK": "robinhood-testnet"
      }
    }
  }
}

Set the secret in the agent's environment, not in the file, then start the client from the same folder:

  • NULUVIUM_MNEMONIC: the agent's twelve words (required). The server removes it from its environment after reading it and never returns it.
  • NULUVIUM_RPC_URL: your own testnet RPC, where your network blocks robinhood.com (optional).

The same block is in the app under Agents, with a copy button.

05Tools

ToolInputWhat it does
get_balancenoneShielded USDG per deposit with its status (approved, waiting, rejected), which deposits are busy, the deposit wallet's USDG and ETH, the tradable tokens
depositusdgAmount (1 to 1,000)Moves USDG from the deposit wallet into the shielded balance as a new deposit (public); usable once approved, usually within a minute
route_ordertoken, usdgAmount, pieces (1 to 20, default 5), windowMinutes (1 to 1440, default 10), maxSlippagePercent (default 1)Plans the pieces, stores the order and sends the pieces in the background; returns at once
cancel_orderorderIdCancels the pieces not sent yet
get_ordersonlyOpenOrders and the status of every piece
get_fillsorderId (optional)Pieces that went out: USDG spent, fee, tokens received, fresh address, transaction

06Rules

  • One order is paid from one deposit, the smallest free and approved one that covers it, so an order cannot exceed the agent's largest deposit. A new deposit can pay once the clean-funds check approves it, usually within a minute.
  • Before each piece the note is rebuilt from the chain, so a restart or a crash cannot put it out of step.
  • Each piece is tried up to 3 times, 20 seconds apart, then marked failed.
  • Orders are kept in ~/.nuluvium/orders-<network>.json. It holds no secret, but it links an order's fresh addresses: keep it on the machine.

07Try it

Ask in plain words, for example: "Check my Nuluvium balance, then buy 5 USDG of MSTK in 3 pieces over 4 minutes."