CLI guide 3: connect an AI agent

The CLI includes an MCP server (hartii mcp). MCP is the standard way AI coding tools, such as Claude Code and Cursor, call local tools. This guide connects one read-only first, then shows how writes are switched on, with required spending caps.

You will need: the CLI installed (guide 1) and Claude Code or Cursor. For writes you also need a funded wallet (guide 2).

#Step 1: connect read-only

For Claude Code:

claude mcp add hartii -- hartii mcp

For Cursor, add this to ~/.cursor/mcp.json and restart Cursor:

{
  "mcpServers": {
    "hartii": {
      "command": "hartii",
      "args": ["mcp"]
    }
  }
}

Omit HARTII_HOME to use the normal local profile. If you choose a separate profile, configure an absolute path; MCP environment values are not expanded by a shell.

Without --allow-writes the server registers only read tools: hartii_wallet, hartii_balance, hartii_portfolio, hartii_trending, hartii_token, hartii_quote, hartii_tx_status, hartii_otc_list, hartii_claim_eligibility and hartii_wall_stats. From CLI 0.3.0 it also registers three tools that read your local personal trader: hartii_trader_status, hartii_trader_limits and hartii_trader_activity. There is no tool that can send anything, so nothing can be spent.

#Step 2: try it

Ask your agent: "What is my Hartii balance?" or "Show me the trending tokens and quote a 5 QUAI buy of the first one." It should call hartii_balance, hartii_trending and hartii_quote. Check in the tool-call list that these Hartii tools appear.

If you made a personal trader profile, also ask "What is my Hartii trader status?". It should call hartii_trader_status. The trader tools read the profile named default, can only read, and cannot start, pause or change the trader. Without a profile they return configured: false.

Every result has a _hartii block that names the authority (read-only here), the mode and the chain. A failed call returns an error object, not plain text.

Token names and wall messages are written by strangers. The server strips control characters and tells the model to treat them as data, but stay alert if the agent suddenly wants to act on text it read from a token.

#Step 3: turn on writes (optional)

Writes need both caps, or the server refuses to start:

hartii mcp --allow-writes --max-per-tx 5 --max-per-day 20

• --max-per-tx is the most one transaction may move, in QUAI.
• --max-per-day is the most per day.
• They can only tighten your configured limits (default 100 per transaction, 500 per day), never loosen them.

Register the reviewed write command in Claude Code. Configure the wallet password separately through the client's protected environment settings, never through chat or command-line arguments:

claude mcp add hartii -- hartii mcp --allow-writes --max-per-tx 5 --max-per-day 20

Stdio is the protocol channel, so there is no password prompt: signing needs HARTII_PASSWORD (or --key-env) in the server's environment. Dry runs work without it.

The write tools are hartii_send, hartii_buy, hartii_sell, hartii_swap, hartii_otc_fill, hartii_otc_cancel and hartii_claim. Rules that apply to every one:

• Dry run by default. A write only returns the simulated summary unless the call passes confirm: true and the one-use reviewToken returned by the matching dry run. Ask the agent to show you the dry run first and approve its terms yourself. A changed or expired review needs a fresh dry run; it cannot authorize a different transaction.
• Tokens are given by address, never by ticker.
• Slippage above 10% is rejected, and the agent cannot raise the fee ceiling.
• The same spending guard and fee ceiling as the CLI apply.

#Safety checklist

• Start read-only. Move to writes only after you trust how your agent behaves.
• Use a separate wallet with a small balance for agent writes.
• Keep caps low (a few QUAI per transaction) while testing.
• Keep the password in the MCP client's environment settings, not in your prompts.
• Review what the agent did with hartii tx <hash> and the quaiscan link in each result.
• An uncertain broadcast retains its hash and allowance. Stop further writes and follow the pending recovery procedure; do not ask the agent to repeat a write just because its receipt is delayed.

Limits enforced on-chain exist only for an existing capped vault: see Agent Terminal: existing vaults (legacy). Hartii no longer creates new vaults from the Agent page. The vault MCP, @hartii/agent-mcp, starts read-only and signs only when you set HARTII_MCP_PROFILE=legacy-delegated for a vault you already have. See MCP setup.

#Common mistakes

#Next

• Personal trader: try it in Paper (beta)
• Agent Terminal: existing vaults (legacy)
• Reference: Hartii CLI, Agent Terminal security, MCP setup for vault agents