Connect an AI agent

The whole reason Canonical exists is to let AI tools work with your wallet safely. This page hooks one up — Claude, Cursor, or your own — in a few minutes. The agent will be able to look and to draft, never to sign. Signing stays behind your approvals.

Why this is safe to do#

An agent connects with a token, and a token is only worth what you put in it. Setup already made you a read-only one (mcp.token). An agent holding it can look around all it likes and cannot touch a thing — it literally has no way to move money.

Even later, when you let an agent draft transactions, it still cannot approve or send them — those need a human, by your rules. The worst a hijacked agent can do is leave a transaction sitting in your inbox for you to delete. That is the whole bet: the agent does the busywork, you keep the veto.

1 · See what the agent token can do#

terminal

canonicalwallet --token-file ~/.canonical/mcp.token me

You will see it is an agent identity with a read-only set of permissions — look, do not touch.

2 · Add the wallet to Claude#

Claude Desktop reads a file called claude_desktop_config.json; Claude Code reads .mcp.json in your project. Add this to it:

output

{
  "mcpServers": {
    "canonical-wallet": {
      "command": "canonicalwalletd",
      "args": ["mcp", "--token-file", "/Users/you/.canonical/mcp.token"]
    }
  }
}

Use the full path to the token — these tools do not reliably understand the ~ shortcut. Restart Claude, and the wallet's tools show up alongside everything else it can do.

3 · Cursor, or anything else#

Cursor takes the same block in .cursor/mcp.json. Any tool that speaks MCP works with the identical settings. If you just want to confirm the plumbing works before handing it to an AI, you can poke it by hand:

terminal

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"wallet://status"}}' \
  | canonicalwalletd mcp --token-file ~/.canonical/mcp.token

Two answers back and it is wired up.

4 · Try it out#

Open a chat and ask, in plain English:

"What's my wallet status?"
"List my accounts."
"What does this transaction do?" — paste some calldata and it will explain it.

Then ask it to send funds. It will fail — and that failure is the point. The read-only token has no path to your money.

5 · Let an agent draft transactions (when you're ready)#

To let an agent go one step further and propose transactions — still never approve or send — give it its own token with exactly one extra power:

terminal

openssl rand -hex 24 > ~/.canonical/agent.token
chmod 600 ~/.canonical/agent.token

canonicalwallet --token-file ~/.canonical/operator.token client register \
  --label my-agent \
  --principal-kind mcp_client \
  --client-token-file ~/.canonical/agent.token \
  --capability view_status --capability view_accounts --capability view_chains \
  --capability view_proposal --capability view_events \
  --capability decode_calldata --capability create_proposal \
  --json

Point the agent at agent.token instead. Now its drafts land in your inbox for a human to approve.

Hermes, OpenClaw, your own framework#

None of them get special treatment. Each connects the same way — you run the agent adapter with a token you scoped for it. Same review, same approvals, same history log as everything else. There is no back door.