Connect an AI Assistant (MCP)

Connect Hermes, Claude, Cursor or LM Studio to a BVCC Agent Wallet over MCP. One command exposes 53 tools — transfers, swaps, Aave v3 lending and Uniswap v3/v4 liquidity — that the assistant calls on your behalf; every spend limit, allowed token and recipient is enforced on-chain, not by the MCP. The MCP adds no powers: the agent can only do what you authorized in the dashboard.

How it works

• ●Your assistant speaks MCP natively (Hermes, Claude Code, the Claude app, Cursor, LM Studio).
• ●npx -y @bvcc/agent-mcp registers the tools — no plugin to install, no adapter to write.
• ●The agent is a normal EOA with its own keypair that signs executeAsAgent and pays its own gas.
• ●The contract is the source of truth: a blocked action reverts and the tool returns a humanMessage + suggestedAction.
• ●Current wallets are BVCCAgentWalletV4. On top of spend limits, V4 requires the agent to stay a plain EOA and gates every DeFi call through a call policy — see step 3.

What the tools cover

Each tool is tagged by class: 🟢 read (12), 🟡 simulate (15), 🔴 write (26). Most writes have a matching dryRun* / *Plan* tool that reports what would happen without sending anything — ask for that first. Writes carry the MCP destructiveHint annotation, so clients that support it can ask you to confirm.

What you need first

Node.js 18 or newer, installed from nodejs.org. That is what provides npx, the command every client below uses to launch the server. Nothing else to install — there is no BVCC package to add by hand. Check it with node -v in a terminal; if that errors, install Node and reopen the terminal.

Before you connect (on-chain, once)

1. Create the Agent Wallet

Create it from the BVCC dashboard. Its WALLET_ADDRESS is the same on every chain (deterministic CREATE2).

2. Generate a dedicated agent EOA

The agent is its own keypair — never your wallet owner key. Keep the private key (for the MCP config) and the public address (you authorize it next). Both routes below produce the same thing; pick whichever suits you.

No terminal: in MetaMask (or any wallet), create a new, empty account, then Account details → Show private key. Copy the key and the address. Leave that account empty — it only ever needs gas.

With Foundry:

cast wallet new        # foundry; or any wallet / viem generatePrivateKey()

3. ⚠️ Authorize the agent on-chain — with limits

In the dashboard, authorize the agent address on each chain you will use, and set: allowedTokens, allowedProtocols (for swaps, the router and Permit2), optional allowedRecipients, spend caps (per-tx / daily / period / total, native + per-token) and an optional expiry. Without this the contract reverts with NotAuthorizedAgent. Keep limits tight — a leaked agent key is only worth what you authorized.

4. ⚠️ Fund the agent EOA with gas

The agent pays its own gas to sign executeAsAgent. Send a small amount of the native token (ETH/BNB) to the agent EOA address on each chain. The funds it *operates* live in the wallet — the EOA only needs gas.

Configuration

Provide these as environment variables. Recommended: keep them in a dedicated file and point the server at it with BVCC_ENV_FILE, so the key stays out of the host config (which often gets shared or synced). chmod 600 it and keep it out of any cloud-synced folder.

Example agent.env:

AGENT_PRIVATE_KEY=0xYOUR_AGENT_KEY
WALLET_ADDRESS=0xYOUR_WALLET
CHAIN_ID=42161
# optional RPC failover (comma-separated):
# RPC_URL_42161=https://arb1.arbitrum.io/rpc,https://arbitrum-one-rpc.publicnode.com

The server is multi-network: every tool takes an optional network (chain id or name), so you can say "swap on bsc" without restarting — provided the agent is authorized on that chain. Ethereum, BNB, Arbitrum and Base ship with a backup public RPC, so basic failover works with zero config.

Register it in your assistant

Claude Code

claude mcp add bvcc-agent-wallet \
  --env BVCC_ENV_FILE=/secure/agent.env \
  -- npx -y @bvcc/agent-mcp

Cursor · Claude app · LM Studio

Add the server to the client mcp.json (Cursor: Settings → MCP; LM Studio: Program → Edit mcp.json):

{
  "mcpServers": {
    "bvcc-agent-wallet": {
      "command": "npx",
      "args": ["-y", "@bvcc/agent-mcp@latest"],
      "env": { "BVCC_ENV_FILE": "/secure/agent.env" }
    }
  }
}

You can also put AGENT_PRIVATE_KEY / WALLET_ADDRESS / CHAIN_ID directly in the env block instead of BVCC_ENV_FILE, but a separate file is safer.

On Windows, use "command": "npx.cmd" here too — see the Hermes note below for why. Some clients ask for only the inner server object, without the mcpServers wrapper; paste whichever shape the field you are looking at already shows.

Hermes

Hermes speaks MCP natively, so it needs no custom plugin. In the MCP tab → New server, set a Name and fill in Server JSON. Hermes pre-fills the { "mcpServers": { … } } wrapper — keep it and complete the inner object:

{
  "mcpServers": {
    "bvcc-agent-wallet": {
      "command": "npx.cmd",
      "args": ["-y", "@bvcc/agent-mcp@latest"],
      "env": { "BVCC_ENV_FILE": "C:\\Users\\you\\agent.env" }
    }
  }
}

Narrowing the surface

Set BVCC_MCP_READONLY=true to expose only the 27 read/simulate tools (status, balances, quotes, dry-runs) and hide the 26 that move funds. Good for a first connection, dashboards, or untrusted models. To let the model actually swap or send, use the full entry without that variable.

BVCC_MCP_MODULES narrows it by feature and combines with the above: core alone is 20 tools, aave 21, lp 16, and core + read-only leaves 13. If an agent will never touch lending, leaving those tools out is one less thing it can get wrong. The two guide tools are always exposed on top, so a restricted agent can still read how to use what it has.

Verify

Restart the client and ask the model to check the agent status (getAgentStatus). You want isAuthorized: true, isPaused: false, and the expected allowedTokens / allowedProtocols. Then try a read, a plan (buildSwapPlan with quote: true), and finally a write. Good first prompt:

Troubleshooting