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

Enrollment trust window (security)

First-run enrollment is trust-on-first-use: whoever holds the CUSTODY_API_KEY at first boot gets their locally-generated P-256 key enrolled as the agent's signer, with no out-of-band confirmation. This creates a window between key issuance and your first enrollment in which a stolen or shared key can be used to enroll an attacker-controlled signer.

• Enroll promptly after the key is issued — start the wallet once on the intended host as soon as you receive the key, so you close the window.
• Treat an unexpected first-run KEY_MISMATCH as a compromise signal, not just "I lost local state." If you boot on a fresh host and immediately hit KEY_MISMATCH (the backend already has a different key enrolled) but you never enrolled before, another host may have enrolled with this API key. Do not simply Force-Re-Enroll — first rotate the API key, then re-enroll from a trusted host. Force-Re-Enroll alone does not evict an attacker who still holds the key.

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_AGENT_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_AGENT_HOME safely. A selected endpoint profile adds a stable endpoint namespace before those paths:

{
  "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). Overrides a selected profile endpoint for one process. | | CUSTODY_AGENT_HOME | no | ~/.agent-wallet | On-disk agent profile/state root. Must be on persistent storage — losing it loses the agent identity. CUSTODY_HOME remains a legacy override; a detected legacy ~/.custody state tree is retained. | | CUSTODY_AGENT_PROFILE | no | active profile | Select a non-secret endpoint profile. Profile state is partitioned by the endpoint digest as well as server-issued agent 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. |

The MCP wallet pins its resolved endpoint for its lifetime. After changing a profile or CUSTODY_AGENT_PROFILE, restart the MCP wallet process before it submits another intent.

Deployment profiles

Use custody-wallet to persist a non-secret endpoint target, then select it for subsequent processes or for one invocation:

custody-wallet profile add staging --api-url https://staging.api.7clave.com
custody-wallet profile use staging
custody-wallet --profile staging whoami

Profiles store only the endpoint. Keep CUSTODY_API_KEY injected through the environment or a secret manager; do not add it to a profile file. Restart a running MCP wallet after changing its selected profile.

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.