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"],
      "env": { "HARTII_HOME": "~/.hartii" }
    }
  }
}

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. 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.

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 it in Claude Code, passing the wallet password through the environment rather than on the command line:

claude mcp add hartii -e HARTII_PASSWORD=<your-password> -- 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. Ask the agent to show you the dry run first and approve it yourself.
• 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.

If you want limits enforced on-chain instead of by local software, give the agent its own key and a capped vault: see Agent Terminal: a capped vault.

#Common mistakes

#Next

• Agent Terminal: a capped vault
• Reference: Hartii CLI, Agent Terminal security, MCP setup for vault agents