{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/blockventurechaincapital-crypto/bvcc-agent-mcp/main/assets/bvcc_wallet.png\" alt=\"BVCC Wallet\" width=\"180\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"https://glama.ai/mcp/servers/blockventurechaincapital-crypto/bvcc-agent-mcp\">\n    <img src=\"https://glama.ai/mcp/servers/blockventurechaincapital-crypto/bvcc-agent-mcp/badges/card.svg\" alt=\"bvcc-agent-mcp MCP server\" />\n  </a>\n</p>\n\n# @bvcc/agent-mcp\n\n**Model Context Protocol server for a BVCC Agent Wallet.** It lets MCP-speaking\nAI runtimes — Claude Code, Cursor, the Claude desktop app — operate a BVCC Agent\nWallet on-chain: check balances and limits, plan and simulate swaps, send tokens,\nswap on Uniswap v3/v4 (including to and from native ETH), **provide liquidity on\nUniswap v3/v4** (including native-ETH pools), and **lend, borrow and unwind\npositions on Aave v3** — including closing or deleveraging a position in safe\nsteps on its own. It also ships built-in **operating guides** (`listGuides` /\n`getGuide`, also exposed as prompts) so an agent can learn how to use each area on\ndemand.\n\nEvery tool is generated from the [`@bvcc/agent-sdk`](https://www.npmjs.com/package/@bvcc/agent-sdk) capability\ncatalog. There is no per-tool code here: add a capability to the SDK catalog and\nit appears here automatically.\n\n> **New here? Start with [QUICKSTART.md](https://github.com/blockventurechaincapital-crypto/bvcc-agent-mcp/blob/main/QUICKSTART.md)** — the full end-to-end\n> setup (create wallet → authorize the agent on-chain → fund it with gas → configure\n> → verify). It covers the two steps people miss without which the agent does nothing.\n\n## Security\n\nThis server **adds no powers**. All limits — spend caps (native + per-token,\ndaily + total), allowed tokens, allowed protocols, recipient whitelist, and a\nglobal pause — are enforced **on-chain** by the Agent Wallet contract. The worst\nany tool can do is bounded by what you authorized for the agent in the BVCC\ndashboard.\n\n- The agent's **private key** is read from the environment, used locally to sign,\n  and **never transmitted**. BVCC does not receive, store, or custody it.\n- Tools are exposed **explicitly** via the SDK catalog — nothing is auto-discovered.\n- Set `BVCC_MCP_READONLY=true` to expose only read/simulate tools (no writes).\n\n## Tools\n\nGenerated from the catalog and tagged by class:\n\n**Core** (wallet, transfers, swaps):\n\n| Class | Tools |\n|-------|-------|\n| 🟢 read | `getAgentStatus`, `getCapabilities`, `getNativeBalance`, `getTokenBalances`, `getRemaining`, `needsApproval` |\n| 🟡 simulate | `buildSwapPlan`, `dryRunSendNative`, `dryRunSendToken`, `dryRunSwapV3`, `dryRunSwapV4` |\n| 🔴 write | `sendNative`, `sendToken`, `approve`, `swapV3`, `swapV4`, `swapToNative`, `swapFromNative` |\n\nA 0.15% BVCC agent fee is charged automatically on-chain on agent actions, separate\nfrom gas and from your spend budget.\n\n**Aave v3 lending** (`aave` module — Arbitrum, Ethereum, BNB, Base, Polygon):\n\n| Class | Tools |\n|-------|-------|\n| 🟢 read | `getAavePositions`, `getAaveMarket` |\n| 🟡 simulate | `dryRunAaveSupply`, `dryRunAaveBorrow`, `aavePlanClosePosition`, `aavePlanDeleverage`, `aavePlanCollateralSwap`, `aavePlanDebtSwap` |\n| 🔴 write | `aaveSupply`, `aaveWithdraw`, `aaveBorrow`, `aaveRepay`, `aaveRepayWithATokens`, `aaveSetCollateral`, `aaveSetEMode`, `aaveClosePosition`, `aaveDeleverage`, `aaveCollateralSwap`, `aaveDebtSwap` |\n\nDeposits and borrows are always **for the wallet itself** — no `to` or `onBehalfOf`\nparameter exists, because the wallet's on-chain call policies pin the beneficiary.\n\n⚠️ **The four `aave*` unwinding tools can send several transactions in one call.**\n`aaveClosePosition`, `aaveDeleverage`, `aaveCollateralSwap` and `aaveDebtSwap` run a\nchunked loop, re-deriving and re-simulating each step from live state. Call the\nmatching `aavePlan*` tool first to see what it intends to do. They stop rather than\nproceed if the health factor would fall below `hfFloor` (default 1.05), if a swap\nprices too far from the Aave oracle, if the loop stops making progress, or if the\nagent's budget would run out.\n\n**Uniswap liquidity** (`lp` module — open, collect, close positions on v3 & v4):\n\n| Class | Tools |\n|-------|-------|\n| 🟢 read | `getV3Position`, `getV4Position` |\n| 🟡 simulate | `dryRunAddLiquidityV3`, `dryRunRemoveLiquidityV3`, `dryRunAddLiquidityV4`, `dryRunRemoveLiquidityV4` |\n| 🔴 write | `addLiquidityV3`, `removeLiquidityV3`, `collectFeesV3`, `burnV3`, `addLiquidityV4`, `removeLiquidityV4`, `collectFeesV4`, `burnV4` |\n\nThe position NFT is minted **to the wallet** and every proceed returns to it —\npinned on-chain. `addLiquidityV3` sizes both sides to the pool's current price\n(full-range by default, or pass ticks). v4 covers **native-ETH pools**; its tools\nneed the v4 PositionManager's DEEP validator active on-chain for the agent, else\nthe action fails closed. Note there is no `increaseLiquidity` on v3 (not\nowner-gated on the NFPM — add by minting a fresh position).\n\n**Guides** (`meta` module — always exposed, help):\n\n| Class | Tools |\n|-------|-------|\n| 🟢 read | `listGuides`, `getGuide` |\n\n`listGuides` names the how-to guides; `getGuide({ area })` returns the playbook for\none area — the recommended workflow and the gotchas, naming the exact tools —\ncovering `getting-started`, `swaps`, `lending` and `liquidity`. They stay available\neven under a module filter, so an agent restricted to one feature can still learn\nhow to use it. The same guides are also exposed as **prompts** (`guide-<area>`) so a\nhuman can pull one as a slash-command.\n\nWrites carry the MCP `destructiveHint` annotation so clients can require\nconfirmation. See [GUIDE.md](https://github.com/blockventurechaincapital-crypto/bvcc-agent-mcp/blob/main/GUIDE.md) for the recommended operating workflow.\n\n## Configuration\n\n**Recommended:** keep the values — above all `AGENT_PRIVATE_KEY` — in a dedicated\nenv file and point the server at it with `BVCC_ENV_FILE`, instead of inlining the\nkey in your MCP host's config (which gets shared, synced and screenshotted).\n`chmod 600` that file and keep it outside any cloud-synced folder. You *can* still\ninline the variables in the host's `env` block if you prefer; host env wins over\nthe file. See [`.env.example`](https://github.com/blockventurechaincapital-crypto/bvcc-agent-mcp/blob/main/.env.example).\n\nExample `agent.env` (path passed via `BVCC_ENV_FILE`):\n\n```bash\nAGENT_PRIVATE_KEY=0xYOUR_AGENT_KEY\nWALLET_ADDRESS=0xYOUR_WALLET\nCHAIN_ID=42161\n```\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `AGENT_PRIVATE_KEY` | yes | Agent EOA private key (`0x` + 64 hex). Used locally only. |\n| `WALLET_ADDRESS` | yes | The BVCC Agent Wallet this agent operates. |\n| `CHAIN_ID` | yes | **Default** chain: `42161` Arbitrum One · `56` BNB · `1` Ethereum · `8453` Base · `137` Polygon · `421614` Arbitrum Sepolia. |\n| `RPC_URL` | no | Custom RPC for the default chain (otherwise a public default). |\n| `RPC_URL_<chainId>` | no | Per-chain RPC override, e.g. `RPC_URL_56`. |\n| `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. |\n| `BVCC_MCP_READONLY` | no | `true` exposes only read/simulate tools. |\n| `BVCC_MCP_MODULES` | no | Comma-separated feature groups to expose: `core`, `aave`, `lp`. Unset = all. |\n\n**Narrowing what the agent can reach.** `BVCC_MCP_READONLY` and `BVCC_MCP_MODULES`\nare independent and combine. If an agent will never touch lending, leaving those\ntools out is one less thing it can get wrong:\n\n```bash\nBVCC_MCP_MODULES=core              # wallet + swaps    (18 + 2 guides = 20)\nBVCC_MCP_MODULES=aave              # Aave lending      (19 + 2 = 21)\nBVCC_MCP_MODULES=lp                # Uniswap liquidity (14 + 2 = 16)\nBVCC_MCP_MODULES=core,aave,lp      # everything (= unset)  (51 + 2 = 53)\nBVCC_MCP_MODULES=core\nBVCC_MCP_READONLY=true             # read-only wallet  (11 + 2 = 13)\n```\n\nThe two guide tools (`listGuides`, `getGuide`, module `meta`) are always exposed on\ntop of these — that is the `+ 2` — so an agent restricted to one feature can still\nread how to use it.\n\nAn unrecognised module name is ignored, so a typo yields a *smaller* surface, never\na larger one. Neither switch is the security boundary — the contract is — but a\nsmaller surface is fewer ways for a confused agent to act.\n\n**Multi-network:** one server operates the agent on any supported chain. Every\ntool takes an optional `network` (chain id or name: `ethereum`, `bsc`, `arbitrum`,\n`base`, `polygon`, `arbitrum-sepolia`), defaulting to `CHAIN_ID` — so you can say \"swap on\nbsc\" without restarting. The wallet address is the same on every chain (CREATE2);\nthe agent must be authorized on each chain you use.\n\n## Install & build\n\n```bash\nnpm install\nnpm run build\nnpm test          # builds + stdio smoke test (no chain calls)\n```\n\n## Connect to a client\n\n### Claude Code\n\n```bash\nclaude mcp add bvcc-agent-wallet \\\n  --env BVCC_ENV_FILE=/secure/agent.env \\\n  -- npx -y @bvcc/agent-mcp\n```\n\n### Cursor / Claude app (`mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"bvcc-agent-wallet\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bvcc/agent-mcp\"],\n      \"env\": { \"BVCC_ENV_FILE\": \"/secure/agent.env\" }\n    }\n  }\n}\n```\n\nThe key lives in `agent.env`, not in the config above. If you'd rather inline it,\nreplace the `env` block with `AGENT_PRIVATE_KEY` / `WALLET_ADDRESS` / `CHAIN_ID`\ndirectly (less safe — the key sits in the host config). Pin a version for\nreproducibility, e.g. `@bvcc/agent-mcp@0.2.1` (see [Upgrading](#upgrading)).\n\n## Upgrading\n\nThe SDK is bundled into this package, so **updating the MCP is all you need** to get\nnew capabilities (Aave lending shipped this way in 0.2.0) — you never install or update\n`@bvcc/agent-sdk` separately.\n\n1. **Pin the version** in your config for reproducibility:\n   ```json\n   \"args\": [\"-y\", \"@bvcc/agent-mcp@0.2.1\"]\n   ```\n   `npx` caches, so an unpinned `@bvcc/agent-mcp` can keep running an old build.\n   To upgrade, bump the number (e.g. `@0.2.1`) — or use `@latest` if you prefer.\n   Global installs: `npm i -g @bvcc/agent-mcp@latest`.\n2. **Restart your MCP client.** New tools from the catalog appear automatically;\n   nothing else in the config changes. The startup banner prints the running\n   version (`[bvcc-agent-mcp vX.Y.Z]`).\n3. ⚠️ **Authorize any new protocol on-chain.** A release that adds a new protocol\n   (e.g. Aave) exposes its tools immediately, but the agent must have that\n   protocol's contract in its `allowedProtocols` — otherwise the action reverts\n   with `ProtocolNotAllowed`. Authorize it from the dashboard, same as a router.\n\nSee [CHANGELOG.md](https://github.com/blockventurechaincapital-crypto/bvcc-agent-mcp/blob/main/CHANGELOG.md) for what each version changes. Versioning follows\nSemVer: patch = fix, minor = new compatible feature, and `0.x` means the API may\nstill change.\n\n## How it works\n\n```\n@bvcc/agent-sdk  ──catalog──►  @bvcc/agent-mcp  ──MCP──►  Claude Code / Cursor / Claude\n   (on-chain limits live in the Agent Wallet contract, not here)\n```\n\nThe server loads the catalog, registers one MCP tool per capability (Zod schema →\ntool input schema, `kind` → tool annotations), and routes each call to the SDK,\nwhich signs with the agent key and submits `executeAsAgent`.\n\n## License\n\nMIT © BlockVenture Chain Capital (BVCC)\n",
  "bytes": 11381,
  "sha": "f4575240493c2a3ec84ece454d2249a3f97fbad30fe2bf267d7071ef543d96b4",
  "repo_slug": "blockventurechaincapital-crypto/bvcc-agent-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_blockventurechaincapital_bvcc_agent__84e1bf5e/readme"
}