bvcc-agent-mcp
Provides tools for operating a BVCC Agent Wallet on Ethereum, including checking balances and limits, planning and simulating swaps, sending tokens, and executing swaps on Uniswap v3/v4.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
@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,
swap on Uniswap v3/v4 (including to and from native ETH), provide liquidity on
Uniswap v3/v4 (including native-ETH pools), and lend, borrow and unwind
positions on Aave v3 — including closing or deleveraging a position in safe
steps on its own. It also ships built-in operating guides (listGuides /
getGuide, also exposed as prompts) so an agent can learn how to use each area on
demand.
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=trueto expose only read/simulate tools (no writes).
Related MCP server: seashail
Tools
Generated from the catalog and tagged by class:
Core (wallet, transfers, swaps):
Class | Tools |
🟢 read |
|
🟡 simulate |
|
🔴 write |
|
wrapNative / unwrapNative turn ETH into WETH and back, one to one. Moving between ETH
and WETH is not a swap: swapFromNative with WETH as the output, or swapToNative with
WETH as the input, does the same wrap or unwrap.
A 0.15% BVCC agent fee is charged automatically on-chain on agent actions, separate from gas and from your spend budget.
Aave v3 lending (aave module — Arbitrum, Ethereum, BNB, Base, Polygon):
Class | Tools |
🟢 read |
|
🟡 simulate |
|
🔴 write |
|
Deposits and borrows are always for the wallet itself — no to or onBehalfOf
parameter exists, because the wallet's on-chain call policies pin the beneficiary.
⚠️ The four aave* unwinding tools can send several transactions in one call.
aaveClosePosition, aaveDeleverage, aaveCollateralSwap and aaveDebtSwap run a
chunked loop, re-deriving and re-simulating each step from live state. Call the
matching aavePlan* tool first to see what it intends to do. They stop rather than
proceed if the health factor would fall below hfFloor (default 1.05), if a swap
prices too far from the Aave oracle, if the loop stops making progress, or if the
agent's budget would run out.
Uniswap liquidity (lp module — open, collect, close positions on v3 & v4):
Class | Tools |
🟢 read |
|
🟡 simulate |
|
🔴 write |
|
The position NFT is minted to the wallet and every proceed returns to it —
pinned on-chain. addLiquidityV3 sizes both sides to the pool's current price
(full-range by default, or pass ticks). v4 covers native-ETH pools; its tools
need the v4 PositionManager's DEEP validator active on-chain for the agent, else
the action fails closed. Note there is no increaseLiquidity on v3 (not
owner-gated on the NFPM — add by minting a fresh position).
Guides (meta module — always exposed, help):
Class | Tools |
🟢 read |
|
listGuides names the how-to guides; getGuide({ area }) returns the playbook for
one area — the recommended workflow and the gotchas, naming the exact tools —
covering getting-started, swaps, lending and liquidity. They stay available
even under a module filter, so an agent restricted to one feature can still learn
how to use it. The same guides are also exposed as prompts (guide-<area>) so a
human can pull one as a slash-command.
Writes carry the MCP destructiveHint annotation so clients can require
confirmation. See GUIDE.md for the recommended operating workflow.
Wallet V5
The server works with every wallet generation and detects which one it is talking to. On a V5 wallet a few things change, and the tools already apply them:
Limits:
0allows nothing (before V5 it meant unlimited) and an empty recipient list allows no recipient. Limits count the 0.15% agent fee too, so stay a little under them;getRemainingshows the real headroom.Swaps run through the Universal Router, between ERC-20 tokens.
swapV3keeps working: on V5 it is sent through the Universal Router for you.Permit2 allowances for swaps and v4 liquidity are granted by the wallet owner when authorizing or renewing the agent, not by the agent.
Native coin and Uniswap v3 liquidity (wrap / unwrap,
swapToNative,swapFromNative, the v3 LP tools) work where their validators are active on that network;getCapabilitiessays so. Elsewhere use WETH and v4 liquidity.Aave: everything except
aaveRepayWithATokens.The owner can pause one agent, block a contract for every agent and renew the expiry.
getAgentStatusandgetCapabilitiesreport all of it.
Anything V5 does not allow comes back as a failed result with a plain explanation, before any gas is spent.
Good to know
Retry or not. Every failed result carries
retryable. When it isfalsethe same call will fail again (a budget is used up, a permission is missing, the balance is short): change the input or ask the owner instead of repeating it.Liquidity ranges as prices. The LP tools take
priceLower/priceUpperinstead of raw ticks. A range that does not contain the current price needs a confirmation: the first call stops and asks, andallowOutOfRange: trueopens it.Gas margin. Transactions are sent with 20% more gas than the estimate; unused gas is not paid.
Source tag. Each transaction ends with 8 bytes naming the tool that built it (the BVCC MCP) and its version, so BVCC can tell which releases are in use and tie failures to a version. It carries nothing about you, your wallet or your agent, and the wallet ignores it.
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=42161Variable | Required | Description |
| yes | Agent EOA private key ( |
| yes | The BVCC Agent Wallet this agent operates. |
| yes | Default chain: |
| no | Custom RPC for the default chain (otherwise a public default). |
| no | Per-chain RPC override, e.g. |
| no | Path to a dedicated env file to load (keeps the key out of the host config). Host env wins over it. |
| no |
|
| no | Comma-separated feature groups to expose: |
| no |
|
Narrowing what the agent can reach. BVCC_MCP_READONLY and BVCC_MCP_MODULES
are independent and combine. If an agent will never touch lending, leaving those
tools out is one less thing it can get wrong:
BVCC_MCP_MODULES=core # wallet + swaps (22 + 2 guides = 24)
BVCC_MCP_MODULES=aave # Aave lending (19 + 2 = 21)
BVCC_MCP_MODULES=lp # Uniswap liquidity (14 + 2 = 16)
BVCC_MCP_MODULES=core,aave,lp # everything (= unset) (55 + 2 = 57)
BVCC_MCP_MODULES=core
BVCC_MCP_READONLY=true # read-only wallet (13 + 2 = 15)The two guide tools (listGuides, getGuide, module meta) are always exposed on
top of these — that is the + 2 — so an agent restricted to one feature can still
read how to use it.
An unrecognised module name is ignored, so a typo yields a smaller surface, never a larger one. Neither switch is the security boundary — the contract is — but a smaller surface is fewer ways for a confused agent to act.
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, polygon, 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@latestCursor / Claude app (mcp.json)
{
"mcpServers": {
"bvcc-agent-wallet": {
"command": "npx",
"args": ["-y", "@bvcc/agent-mcp@latest"],
"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). @latest keeps you on the
newest release; to stay on one version instead, see Upgrading.
Upgrading
The SDK is bundled into this package, so updating the MCP is all you need to get
new capabilities (Aave lending shipped this way in 0.2.0) — you never install or update
@bvcc/agent-sdk separately.
Use
@latest(recommended), as in the examples above.npxcaches, so a plain@bvcc/agent-mcpwith no tag can keep running an old build;@latestchecks for a newer one each time the client starts the server. To stay on one version instead, pin it and bump the number yourself when you upgrade:"args": ["-y", "@bvcc/agent-mcp@0.3.1"]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 withProtocolNotAllowed. Authorize it from the dashboard, same as a router.
Knowing when there is a new version. When the server starts, it asks the public npm
registry which version of @bvcc/agent-mcp is the latest. This runs in the background
and gives up after 2 seconds, so startup never waits on it or fails because of it. If a
newer version is out, the log prints [bvcc-agent-mcp] update available 0.3.1 → 0.3.2 …
and getAgentStatus returns updateAvailable: { current, latest, command, changelogUrl },
which the agent passes on to you once. The request carries nothing about you, your wallet
or your agent, though npm does see your IP address, the same as with any npm install.
To turn it off, set BVCC_NO_UPDATE_CHECK=1.
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.
License
MIT © BlockVenture Chain Capital (BVCC)
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
MCP server for the Z1N Protocol - on-chain identity for AI agents on Polygon
PHANTOM ID MCP payment server: agent-to-agent USDC payments on Base.
Agent-commerce MCP server for x402/USDC payments and affiliate splits on Base.
Related MCP Servers
- AlicenseCqualityDmaintenanceSelf-hosted wallet MCP server for AI agents. Provides 42 tools for multi-chain crypto operations: transfers, token management, DeFi (swap, lend, stake, bridge, perp), NFT, smart contracts, and x402 payments. Supports EVM and Solana with policy engine, spending limits, and human approval.6029MIT
- AlicenseNot gradedqualityDmaintenanceAgent-native, self-hosted MCP server for crypto trading and DeFi management. Enables agents to query balances, execute trades, and manage positions with a policy engine and secure key storage.8Apache 2.0
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server enabling AI agents to manage EVM wallets, check balances, swap tokens, and securely execute transactions via 1Claw Intents without exposing private keys.14,078 PyPIMIT
- AlicenseCqualityCmaintenanceWeb3 MCP proxy server for AI agents: EVM execution, DeFi swaps, bridges, advanced orders, market data, wallet management, and confirmation-gated writes.10091 npm1MIT