MCP 服务器

bvcc-agent-mcp

Non-custodial BVCC Agent Wallet MCP server: let an AI agent check balances, send native/ERC-20, approve, and swap on Uniswap v3/v4 across Ethereum, BNB Chain, Arbitrum and Base, within on-chain enforced limits.

README

@bvcc/agent-mcp

Model Context Protocol server for a BVCC Agent Wallet. It lets MCP-speaking AI runtimes — Claude Code, Cursor, the Claude desktop app — operate a BVCC Agent Wallet on-chain: check balances and limits, plan and simulate swaps, send tokens, and swap on Uniswap v3/v4.

Every tool is generated from the @bvcc/agent-sdk capability catalog. There is no per-tool code here: add a capability to the SDK catalog and it appears here automatically.

New here? Start with QUICKSTART.md — the full end-to-end setup (create wallet → authorize the agent on-chain → fund it with gas → configure → verify). It covers the two steps people miss without which the agent does nothing.

Security

This server adds no powers. All limits — spend caps (native + per-token, daily + total), allowed tokens, allowed protocols, recipient whitelist, and a global pause — are enforced on-chain by the Agent Wallet contract. The worst any tool can do is bounded by what you authorized for the agent in the BVCC dashboard.

The agent's private key is read from the environment, used locally to sign, and never transmitted. BVCC does not receive, store, or custody it.
Tools are exposed explicitly via the SDK catalog — nothing is auto-discovered.
Set BVCC_MCP_READONLY=true to expose only read/simulate tools (no writes).

Tools

Generated from the catalog and tagged by class:

Class	Tools
🟢 read	`getAgentStatus`, `getCapabilities`, `getNativeBalance`, `getTokenBalances`, `getRemaining`, `needsApproval`
🟡 simulate	`buildSwapPlan`, `dryRunSendNative`, `dryRunSendToken`, `dryRunSwapV3`, `dryRunSwapV4`
🔴 write	`sendNative`, `sendToken`, `approve`, `swapV3`, `swapV4`

Writes carry the MCP destructiveHint annotation so clients can require confirmation. See GUIDE.md for the recommended operating workflow.

Configuration

Recommended: keep the values — above all AGENT_PRIVATE_KEY — in a dedicated env file and point the server at it with BVCC_ENV_FILE, instead of inlining the key in your MCP host's config (which gets shared, synced and screenshotted). chmod 600 that file and keep it outside any cloud-synced folder. You can still inline the variables in the host's env block if you prefer; host env wins over the file. See .env.example.

Example agent.env (path passed via BVCC_ENV_FILE):

AGENT_PRIVATE_KEY=0xYOUR_AGENT_KEY
WALLET_ADDRESS=0xYOUR_WALLET
CHAIN_ID=42161

Variable	Required	Description
`AGENT_PRIVATE_KEY`	yes	Agent EOA private key (`0x` + 64 hex). Used locally only.
`WALLET_ADDRESS`	yes	The BVCC Agent Wallet this agent operates.
`CHAIN_ID`	yes	Default chain: `42161` Arbitrum One · `56` BNB · `1` Ethereum · `8453` Base · `421614` Arbitrum Sepolia.
`RPC_URL`	no	Custom RPC for the default chain (otherwise a public default).
`RPC_URL_<chainId>`	no	Per-chain RPC override, e.g. `RPC_URL_56`.
`BVCC_ENV_FILE`	no	Path to a dedicated env file to load (keeps the key out of the host config). Host env wins over it.
`BVCC_MCP_READONLY`	no	`true` exposes only read/simulate tools.

Multi-network: one server operates the agent on any supported chain. Every tool takes an optional network (chain id or name: ethereum, bsc, arbitrum, base, arbitrum-sepolia), defaulting to CHAIN_ID — so you can say "swap on bsc" without restarting. The wallet address is the same on every chain (CREATE2); the agent must be authorized on each chain you use.

Install & build

npm install
npm run build
npm test          # builds + stdio smoke test (no chain calls)

Connect to a client

Claude Code

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

Cursor / Claude app (`mcp.json`)

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

The key lives in agent.env, not in the config above. If you'd rather inline it, replace the env block with AGENT_PRIVATE_KEY / WALLET_ADDRESS / CHAIN_ID directly (less safe — the key sits in the host config). Pin a version for reproducibility, e.g. @bvcc/agent-mcp@0.1.4 (see Upgrading).

Upgrading

The SDK is bundled into this package, so updating the MCP is all you need to get new capabilities (e.g. a future Aave release) — you never install or update @bvcc/agent-sdk separately.

Pin the version in your config for reproducibility:
```
"args": ["-y", "@bvcc/agent-mcp@0.1.4"]
```
npx caches, so an unpinned @bvcc/agent-mcp can keep running an old build. To upgrade, bump the number (e.g. @0.2.0) — or use @latest if you prefer. Global installs: npm i -g @bvcc/agent-mcp@latest.
Restart your MCP client. New tools from the catalog appear automatically; nothing else in the config changes. The startup banner prints the running version ([bvcc-agent-mcp vX.Y.Z]).
⚠️ Authorize any new protocol on-chain. A release that adds a new protocol (e.g. Aave) exposes its tools immediately, but the agent must have that protocol's contract in its allowedProtocols — otherwise the action reverts with ProtocolNotAllowed. Authorize it from the dashboard, same as a router.

See CHANGELOG.md for what each version changes. Versioning follows SemVer: patch = fix, minor = new compatible feature, and 0.x means the API may still change.

How it works

@bvcc/agent-sdk  ──catalog──►  @bvcc/agent-mcp  ──MCP──►  Claude Code / Cursor / Claude
   (on-chain limits live in the Agent Wallet contract, not here)

The server loads the catalog, registers one MCP tool per capability (Zod schema → tool input schema, kind → tool annotations), and routes each call to the SDK, which signs with the agent key and submits executeAsAgent.