@7clave/mcp-wallet

Local stdio MCP server that exposes a 7clave custody wallet to any MCP host (Claude Desktop, Claude Code, Cursor, Continue, OpenCode, Hermes, …).

Full setup walkthrough, deployment guide, and security notes: https://mcp.7clave.com/wallet/guide.html

Install

You don't need to install this package by hand. Every host config below uses npx, which fetches and caches the package on first run. As long as you have Node ≥ 22 on PATH, editing the host config is the only step.

Prefer a stable global binary? Run npm install -g @7clave/mcp-wallet once and replace "command": "npx", "args": ["-y", "@7clave/mcp-wallet"] with "command": "mcp-wallet" in any config below.

Get a CUSTODY_API_KEY

This package does not self-serve credentials. A CUSTODY_API_KEY is an agent enrollment key issued by your custody operator (the team running the backend). Workflow:

1. Operator creates an agent in the dashboard and copies the agent_… key.
2. They hand it to you out-of-band (1Password, Bitwarden, secrets manager).
3. You paste it into the MCP host config below.

Treat it like a long-lived API key. On first boot the wallet enrolls with the backend and pins a per-agent identity to ~/.custody/; that on-disk identity becomes the load-bearing secret thereafter.

Quick start — by host

In every case, CUSTODY_API_KEY is the only required env var.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "7clave-wallet": {
      "command": "npx",
      "args": ["-y", "@7clave/mcp-wallet"],
      "env": { "CUSTODY_API_KEY": "agent_…" }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add 7clave-wallet \
  --env CUSTODY_API_KEY=agent_… \
  -- npx -y @7clave/mcp-wallet

Cursor

Settings → MCP → Add Server:

{
  "7clave-wallet": {
    "command": "npx",
    "args": ["-y", "@7clave/mcp-wallet"],
    "env": { "CUSTODY_API_KEY": "agent_…" }
  }
}

Other hosts (OpenCode, Hermes, Continue, …)

Use the same shape — command: "mcp-wallet" plus the env block. Consult your host's MCP docs for the config file location.

Multiple agents on one machine

Each agent just needs its own CUSTODY_API_KEY. State under CUSTODY_HOME is partitioned per-agent by the server-issued agent UUID (keys/<agent_id>/…, actions/<agent_id>/…, logs/<agent_id>/…), so any number of agents share one CUSTODY_HOME safely:

{
  "mcpServers": {
    "7clave-alice": {
      "command": "npx",
      "args": ["-y", "@7clave/mcp-wallet"],
      "env": { "CUSTODY_API_KEY": "agent_…" }
    },
    "7clave-bob": {
      "command": "npx",
      "args": ["-y", "@7clave/mcp-wallet"],
      "env": { "CUSTODY_API_KEY": "agent_…" }
    }
  }
}

Configuration

| Var | Required | Default | Purpose | |---|---|---|---| | CUSTODY_API_KEY | yes | — | Agent enrollment key from your custody operator. | | CUSTODY_API_URL | no | https://api.7clave.com | Backend URL. HTTPS only (loopback allowed for local dev). Override only when self-hosting. | | CUSTODY_HOME | no | ~/.custody | On-disk state root. Must be on persistent storage — losing it loses the agent identity. Safe to share across multiple agents; each agent's state is partitioned under its server-issued UUID. | | CUSTODY_DEBUG | no | off | 1 to write a file log; stderr to log to stderr. | | CUSTODY_LOG_FILE | no | — | Override log target when CUSTODY_DEBUG=1. |

Tools

| Tool | Purpose | |---|---| | get_balance | Token balances across the agent's wallets (flat token rows). | | list_wallets | Per-wallet view of what this agent can act on. | | get_address | Receive addresses for wallets this agent can deposit into. | | transfer | On-chain transfer to an external 0x address. | | fund | Move tokens between two wallets the agent owns. | | x402_pay | Sign one x402 challenge term; optionally deliver the paid HTTP retry. | | sign_typed_data | Sign arbitrary EIP-712 TypedData (Polymarket, Safe, …). | | get_action_status | Poll a previously-submitted action to its terminal state. | | list_actions | List actions this agent has on disk (resume surface). |

State-changing tools return an action envelope: { action_id, status, result?, message? }. status is one of completed, pending, requires_approval, approved, processing, rejected, failed. Action IDs persist across restarts; resume with list_actions / get_action_status.

Versioning

Pre-1.0. The wire contract (tool names, env-var names, envelope shape) is intended to be stable; internals may shift between minor versions. Breaking changes bump the minor version. See CHANGELOG.md.

License

Apache-2.0. See LICENSE.