Connect an AI Assistant (MCP)

Connect Hermes, Claude, Cursor or LM Studio to a BVCC Agent Wallet over MCP. One command exposes 16 tools (send, swap, balances, limits) 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.

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

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. Full detail in Agent Integration.

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. The 4 mainnets 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"],
      "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.

Hermes

Hermes speaks MCP natively, so it needs no custom plugin. In the MCP tab → New server, set a Name and paste into Server JSON — but here Hermes expects only the server object, *without* the { "mcpServers": { … } } wrapper:

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

Read-only mode

Set BVCC_MCP_READONLY=true to expose only the 11 read/simulate tools (status, balances, quotes, dry-runs) and hide the 5 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.

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