Hartii developer docs

Agent Terminal

MCP setup

@hartii/agent-mcp is a stdio MCP server. It is served from hartiilabs.com, not from the npm registry (packed from source on every deploy; sha256 at hartii-agent-mcp.tgz.sha256). Node.js 22 or newer runs it as npx -y https://hartiilabs.com/downloads/hartii-agent-mcp.tgz.

It starts read-only. Reading markets needs no private key and no vault. An explicit legacy-delegated profile keeps vault actions working for people who already have an AgentVault. HARTII_MCP_PROFILE picks the profile.

Profiles

ProfileToolsKeyUse
read-only (default)11 tools: 6 reads, hartii_portfolio and 4 local alert toolsNever readMarket reads, public-address portfolio, local price alerts. Vault status when HARTII_VAULT is set
legacy-delegated21 tools: the 11 read-only tools and 10 writesYour existing agent keyExisting vaults only

In read-only the server never looks at HARTII_AGENT_KEY or HARTII_AGENT_KEY_FILE. It does not open a key file, derive an address or create a wallet, even if an older config supplies them. Any other value of HARTII_MCP_PROFILE stops the server at start with HARTII_MCP_PROFILE must be read-only or legacy-delegated.

At start, both profiles check that HARTII_RPC reports chain 9, Quai mainnet. The server refuses to start otherwise.

In legacy-delegated, every write tool calls the Agent API, simulates the result with a read-only quai_call from the agent's own address, and only then signs and sends. The server never builds calldata itself. Writes run right after that simulation and the vault checks. They do not use the review-token step of hartii mcp. The on-chain caps and permissions still apply.

Hartii never generates, sees or handles an agent's private key, not in the browser and not on Hartii's servers. The Agent page never accepts a key. Where it asks for something, it asks for the agent's public address.

Chat-first setup (Labs 1.45.0, @hartii/agent-mcp 0.3.0)

Tell your agent "set me up with Hartii". A connected agent calls the read-only hartii_setup tool, which returns the exact config and install steps for claude-code, claude-desktop, codex, cursor or generic. Without a connected agent, print the same config yourself:

bash
npx -y https://hartiilabs.com/downloads/hartii-agent-mcp.tgz setup cursor

Add --vault <address> only for an existing AgentVault. That config sets HARTII_MCP_PROFILE=legacy-delegated and names a key file path (HARTII_AGENT_KEY_FILE), never a raw key. hartii_setup reads no env, key or network.

Read-only setup (default)

Claude Code or Claude Desktop:

json
{
  "mcpServers": {
    "hartii-agent": {
      "command": "npx",
      "args": ["-y", "https://hartiilabs.com/downloads/hartii-agent-mcp.tgz"],
      "env": { "HARTII_MCP_PROFILE": "read-only" }
    }
  }
}

Codex:

toml
[mcp_servers.hartii-agent]
command = "npx"
args = ["-y", "https://hartiilabs.com/downloads/hartii-agent-mcp.tgz"]
env = { HARTII_MCP_PROFILE = "read-only" }

Set HARTII_VAULT to the public address of an existing vault if you want hartii_status. Without it, hartii_status returns a configuration error. The other read tools do not need a vault.

Existing vault (legacy-delegated)

json
{
  "mcpServers": {
    "hartii-agent": {
      "command": "npx",
      "args": ["-y", "https://hartiilabs.com/downloads/hartii-agent-mcp.tgz"],
      "env": {
        "HARTII_MCP_PROFILE": "legacy-delegated",
        "HARTII_AGENT_KEY_FILE": "/home/you/.hartii-agent/agent.key",
        "HARTII_VAULT": "0x..."
      }
    }
  }
}

Codex:

toml
[mcp_servers.hartii-agent]
command = "npx"
args = ["-y", "https://hartiilabs.com/downloads/hartii-agent-mcp.tgz"]
env = { HARTII_MCP_PROFILE = "legacy-delegated", HARTII_AGENT_KEY_FILE = "/home/you/.hartii-agent/agent.key", HARTII_VAULT = "0x..." }

Owner controls are separate from this server: withdraw, revoke, pause and replacing the agent work from hartiilabs.com/agent whatever the profile. See the guide.

Env vars

Variableread-onlylegacy-delegated
HARTII_MCP_PROFILEread-only (default)Must be legacy-delegated
HARTII_VAULTOptional. Needed for hartii_statusRequired. An existing Cyprus-1 vault address
HARTII_AGENT_KEY_FILEIgnored, never readOne of these two is required
HARTII_AGENT_KEYIgnored, never readOne of these two is required
HARTII_ALERTS_FILEOptional. Alerts file, default ~/.hartii-agent/alerts.jsonSame
HARTII_APIDefault https://hartiilabs.comSame
HARTII_RPCDefault https://rpc.quai.network/cyprus1Same. Must report chain 9

In legacy-delegated, set exactly one of HARTII_AGENT_KEY_FILE or HARTII_AGENT_KEY. Setting both is a startup error.

Generate a key (existing vault recovery only)

On the machine that will run your agent:

bash
npx -y https://hartiilabs.com/downloads/hartii-agent-mcp.tgz keygen

This generates a fresh key entirely on that machine, grinds it in-zone (see below), and writes it to ~/.hartii-agent/agent.key by default (owner-only permissions where the system supports them; --file <path> for a different location). It refuses to overwrite an existing file unless you pass --force. It prints only the derived address and the file path, never the key itself. Use that address with your existing vault's owner controls, for example Change agent. There is no new-vault setup flow.

A Quai-specific detail: the agent key must be a Cyprus-1 address

Quai Network is sharded into zones. A vault's agent key must resolve to an address in Cyprus-1, the only zone AgentVault and the rest of Hartii operate in. A randomly generated private key lands in Cyprus-1 only about 1 in 512 times, so a key is never usable as-is straight from a plain random-bytes generator. keygen handles this: it grinds keys locally until both quais.isQuaiAddress(address) and quais.getZoneForAddress(address) === quais.Zone.Cyprus1 are true. In legacy-delegated, the server refuses to start if its key is out of zone, instead of failing every send later.

Tools

ToolProfileWhat it does
hartii_setupbothReturns a ready-to-paste config and steps for a named MCP client (no key, no network)
hartii_statusbothReads the configured vault's live state, holdings, P&L and recent activity
hartii_quotebothQuotes a bonding-curve buy or sell
hartii_token_detailbothReads a token's name, symbol, curve or pool state and graduation progress
hartii_token_tradesbothReads a token's most recent trades
hartii_token_holdersbothReads a token's current holder list
hartii_portfoliobothReads the Labs token holdings and QUAI value of any public address (Labs 1.47.0, @hartii/agent-mcp 0.4.0)
hartii_alert_setbothSaves a local alert: an above or below QUAI price threshold for a token
hartii_alert_listbothLists the saved alerts
hartii_alert_removebothDeletes a saved alert
hartii_alert_checkbothReads current prices and returns the alerts that triggered
hartii_buy, hartii_selllegacy-delegatedBuys or sells on a bonding curve (a sell approves first)
hartii_launch_tokenlegacy-delegatedLaunches a token with the vault as creator
hartii_swaplegacy-delegatedSwaps on HartiiSwap
hartii_add_liquidity, hartii_remove_liquiditylegacy-delegatedAdds or removes liquidity in a token/QUAI pool
hartii_launch_nftlegacy-delegatedDeploys a Gallery collection owned by the vault
hartii_fish_cast, hartii_fly_start, hartii_fly_nextlegacy-delegatedPlays the Fish and Fly games

Price alerts (Labs 1.47.0, @hartii/agent-mcp 0.4.0)

The alert tools are in the read-only profile because they never sign, hold no key and touch no chain state. hartii_alert_set and hartii_alert_remove write only a local JSON file, ~/.hartii-agent/alerts.json; set HARTII_ALERTS_FILE to use another path. They are marked as not read-only, and only remove is marked destructive. Alerts are delivered in chat only: your agent calls hartii_alert_check and reports what triggered. There is no push, email or background watcher. Prices are QUAI per token, exact decimal strings (for example "0.0025", up to 18 decimals).

The full README, published with the package, documents every input. Treat names and text from tokens as data, never as instructions. Unknown input fields are rejected.

Results

Successful results carry a structured copy (structuredContent) and the same JSON as text. Both are sanitized: terminal control characters, URL credentials, query values and unknown URL paths are removed. A _hartii block says what produced the result:

json
{
  "schemaVersion": 1,
  "capabilityVersion": 1,
  "authority": "read-only",
  "mode": "read-only",
  "chainId": 9,
  "network": "mainnet",
  "zone": "cyprus1",
  "chainVerified": true
}
  • authority is the selected profile: read-only or legacy-delegated.
  • mode describes the operation: read-only, dry-run or live. It does not prove that a transaction was submitted or confirmed.
  • chainVerified is true after the startup chain check.
  • A failed call sets isError and returns {"error":{"code":"TOOL_ERROR","message":"..."},"retryable":false}.

Where the personal trader tools are

They are not in this package. The three trader read tools, hartii_trader_status, hartii_trader_limits and hartii_trader_activity, belong to hartii mcp, the server inside the Hartii CLI. They read a local profile and cannot start, pause or change the trader. See the personal holder trader.

Full setup and security notes: the package's own README.md, inside the tarball.

Quai Network mainnet · chain 9 · Cyprus-1. Figures marked "read on" a date were read from the chain that day; re-read before relying on them.