Content
# 🚀 CavalRe v1.1.0 MCP Server
## **The Liquidity Layer for Autonomous Financial AI Agents**
> Build AI agents that execute complex DeFi strategies safely, atomically, and with institutional-grade accounting.
[](https://github.com/RedRobotKK/CavalRe_MCP/releases/tag/v1.1.0)
[](SECURITY.md)
[](docs/testing/test-report.md)
[](docs/MATURITY.md)
[📖 Docs](docs/) • [🏗️ Architecture](#architecture) • [🔐 Security](SECURITY.md) • [🌊 CavalRe Core](https://github.com/CavalRe/cavalre-contracts) • [💬 Discord](https://discord.gg/VA6MhZ8cVb)
---
## 🤖 What This Is (And Isn't)
### What You Get
```
You: "Rebalance my portfolio to 60% ETH, 30% stablecoins, 10% alts"
↓
AI Agent: [Interprets intent via LLM]
↓
CavalRe MCP: [Calls atomic basket swap primitive]
↓
CavalRe Core: [Double-entry ledger accounting validates trade]
↓
Multiswap: [Executes all assets in ONE atomic transaction]
↓
Result: ✅ Rebalanced. ✅ Audited. ✅ No slippage from fragmentation.
```
### Not This
❌ Retail trading bot (this is for agent builders)
❌ Generic DeFi API wrapper (this is specialized)
❌ Production-ready (this is a promising prototype with real architecture)
### For Whom
✅ **AI/ML engineers** building autonomous trading agents
✅ **DeFi protocol teams** needing basket execution
✅ **RWA platforms** requiring institutional accounting
✅ **Asset managers** wanting to delegate to AI safely
---
## 🌟 Your Competitive Advantage (Why This Matters)
Most crypto MCP servers are **generic API wrappers**. CavalRe is different.
### Three Structural Edges
#### 1️⃣ **Accounting-First Determinism**
Traditional MCP servers just bundle Web3 calls. CavalRe integrates a **double-entry ledger** that ensures mathematical precision before any trade executes.
```
TRADITIONAL MCP CAVALRE MCP
(Trust the numbers) (Verify the numbers)
┌─────────────────┐ ┌─────────────────────────────┐
│ LLM says: │ │ LLM says: │
│ "Swap 10 ETH" │ │ "Swap 10 ETH for USDC" │
│ │ │ │
│ → Call Uniswap │ │ → Build double-entry ledger │
│ → Hope it works │ │ • Debit ETH │
│ → No audit trail│ │ • Credit USDC │
│ │ │ │
│ Result: │ │ → Validate accounting balances
│ ⚠️ Black box │ │ │
└─────────────────┘ │ → Execute only if balanced │
│ → Immutable audit trail │
│ │
│ Result: │
│ ✅ Deterministic │
│ ✅ Auditable │
│ ✅ Institutional-grade │
└─────────────────────────────┘
```
**Why this matters:** Tax compliance, regulatory audits, institutional clients all require proof that every penny moved was accounted for.
#### 2️⃣ **Atomic Basket Execution**
Instead of spamming 10 separate swaps (each with slippage), CavalRe routes **all assets through one atomic transaction**.
```
FRAGMENTED EXECUTION CAVALRE BASKET EXECUTION
(Multiple txs = slippage) (One tx = optimal)
Before: 60% ETH, 20% USDC Before: 60% ETH, 20% USDC
After: Should be 40% ETH After: Should be 40% ETH
Step 1: Swap ETH → USDC Step 1: Atomic swap
⚠️ Price impact Pay: 20 ETH
Receive: 60% USDT
Step 2: Swap partial USDC ↓ + 40% USDC
→ Another price hit
Result:
Step 3: Handle dust ✅ Single transaction
→ More slippage ✅ No repeated impact
✅ 2-3x better capital efficiency
Result:
⚠️ Lost 2-3% to slippage
```
**Impact:** A $10M portfolio rebalance saves $200k-300k in execution costs.
#### 3️⃣ **RWA (Real-World Asset) Alignment**
Tokenized stocks, bonds, commodities. These need institutional accounting + atomic settlement. CavalRe was built for this.
```
Retail DeFi Agent CavalRe Agent (RWA-Ready)
┌──────────────────┐ ┌─────────────────────────┐
│ Trade memcoins │ │ Rebalance indexed fund │
│ Swap on DEX │ │ with real stocks + bonds│
│ Move on │ │ │
│ │ │ Execute atomically │
│ ✅ Fast │ │ Track positions │
│ ❌ Not auditable │ │ Calculate P&L │
│ ❌ No compliance │ │ Report to regulator │
│ │ │ │
│ │ │ ✅ Fast │
│ │ │ ✅ Auditable │
│ │ │ ✅ Compliant │
└──────────────────┘ └─────────────────────────┘
```
---
## 🏗️ System Architecture: How It Actually Works
The Full Stack
```
┌────────────────────────────────────────────────────────────────────────────│ YOUR LLM AGENT │
│ (Claude, GPT, Custom) │
│ "Rebalance to 60/30/10, but only if gas <100 gwei" │
└────────────────────────────┬────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ CAVALRE MCP SERVER (This Repository) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 1. Parse Intent │ │
│ │ Extract: action=REBALANCE, targets={60/30/10}, constraint=gas │ │
│ │ │ │
│ │ 2. Fetch Current State │ │
│ │ Query wallet: "Current portfolio is 70% ETH, 15% stables, 15%"│ │
│ │ │ │
│ │ 3. Build Safe Ledger │ │
│ │ Debit: 10% ETH Credit: 15% stables (balanced?) │ │
│ │ │ │
│ │ 4. Validate Constraints │ │
│ │ Gas check: 45 gwei < 100 gwei ✅ │ │
│ │ Position check: 60% <= position_limit ✅ │ │
│ │ │ │
│ │ 5. Call CavalRe Router │ │
│ │ {action: "BASKET_SWAP", │ │
│ │ pay: 10_ETH, │ │
│ │ receive: {60% USDT, 40% DAI}, │ │
│ │ nonce: 42, │ │
│ │ constraints: {...}} │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└────────────────────────┬─────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ CAVALRE CORE PROTOCOL (github.com/CavalRe) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Double-Entry Ledger Validation │ │
│ │ ┌─────────────────┬─────────────────┐ │ │
│ │ │ DEBIT │ CREDIT │ │ │
│ │ ├─────────────────┼─────────────────┤ │ │
│ │ │ ETH: -10 │ USDT: +6 │ │ │
│ │ │ │ DAI: +4 │ ││ │ │ SUM: -10 │ SUM: +10 ✅ Balanced │ │
│ │ └─────────────────┴─────────────────┘ │ │
│ │ │ │
│ │ Quote Multiswap Pool │ │
│ │ "Can you take 10 ETH for 6 USDT + 4 DAI?" │ │
│ │ → Check pool reserves │ │
│ │ → Calculate dynamic weights │ │
│ │ → Return quote + slippage estimate │ │
│ │ │ │
│ │ Validate Quote vs. Constraints │ │
│ │ Price impact: 0.2% ✅ (within 2% limit) │ │
│ │ │ │
│ │ Build Transaction │ │
│ │ {to: Multiswap, data: encoded_swap, value: 10_ETH, nonce: │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└────────────────────────┬─────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ MULTISWAP LIQUIDITY POOL │
│ (github.com/CavalRe/cavalre-contracts) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Unified Multi-Asset Pool │ │
│ │ │ │
│ │ Pool Assets: │ │
│ │ • ETH: $50M (scale = 50) │ │
│ │ • USDT: $30M (scale = 30) │ │
│ │ • DAI: $20M (scale = 20) │ │
│ │ • Other tokens... │ │
│ │ │ │
│ │ Incoming Swap: │ │
│ │ Pay: 10 ETH (value flow = -10) │ │
│ │ Receive: [60% USDT, 40% DAI] (value flow = +10) │ │
│ │ │ │
│ │ Execute: Value conserved ✅ │ │
│ │ Price impact: Spread across 2 assets = lower impact │ │
│ │ │ │
│ │ Result: Atomic, deterministic, optimal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└────────────────────────┬─────────────────────────────────────────────────────┘
│
↓
✅ SETTLED
Portfolio rebalanced. Immutable record.
Audit trail complete. Agent happy.
```
---
## Real User Flow: How an AI Agent Uses This
### Scenario: Autonomous Hedge Fund Manager
```
TIME: 3:00 AM (During market volatility spike)
────────────────────────────────────────────────────────────
[1] MARKET EVENT
Bitcoin volatility: 18% → 42%
Your fund's target: "Rebalance to 80% stables if vol >35%"
[2] AI AGENT WAKES UP
LLM detects: "volatility_spike = true"
LLM decision: "Execute rebalancing now"
[3] CAVALRE MCP RECEIVES REQUEST
Intent: Shift from 50% risky to 80% stablecoins
Current: {BTC: 40%, ETH: 30%, USDC: 30%}
Target: {BTC: 10%, ETH: 10%, USDC: 80%}
Trades needed:
• Sell 30 BTC
• Sell 20 ETH
• Buy 70 USDC worth of (BTC, ETH)
[4] BUILD LEDGER (Core Accounting)
Debit: 30 BTC, 20 ETH (leaving portfolio)
Credit: 70 USDC equivalent (entering portfolio)
✅ Balanced
[5] SAFETY CHECKS
✅ Gas price 32 gwei < 100 gwei limit
✅ Position size 70 USDC < $5M limit
✅ Slippage estimate 0.4% < 2% limit
✅ RPC consensus (3/3 endpoints agree)
[6] CALL MULTISWAP
Single atomic basket swap:
Pay: 30 BTC + 20 ETH
Receive: 70 USDC (in optimal mix)
[7] EXECUTE
One transaction, one settlement, done.
[8] RECORD
Immutable audit entry:
• Timestamp: 2026-07-18 03:00:42 UTC
• Trigger: Volatility spike
• Decision: Rebalance to 80% stables
: ✅ Balanced
• Execution: ✅ Atomic
• Gas: 142 gwei
• Slippage: 0.38%
[9] SLEEP
Agent monitored everything rebalanced.
No manual intervention needed. No operational risk.
────────────────────────────────────────────────────────────
Result: $500M fund rebalanced in ONE transaction while you sleep.
```
---
## What We're Honest About
This is a **promising prototype**, not yet battle-tested production code. Here's what's real and what's still coming:
### What Works Now
- Full 9-layer LLM pipeline (intent → execution)
- Zero-custody security model (keys never leave device)
- Dual-state execution (sandbox + production)
- Circuit breaker protection (irreversible on exploit)
- Immutable audit trails (compliance-ready)
- 400+ tests, 95% coverage
### What's Coming (Next 8 Weeks)
- **Event-driven system** - React to market signals automatically
- **Tax calculation layer** - Track P&L automatically
- **HITL/Autonomous modes** - Human-in-the-loop + full automation
- **Registry & - Discover and connect to agents
- **Secure update - Deploy fixes without restarting
### ⚠️ Real Risks We See
**Cold Start Liquidity**: If Multiswap pools are thin, execution quality suffers regardless of how smart the MCP is.
**Prompt Injection**: MCP servers that parse LLM output are vulnerable to manipulation. We validate every command before passing to the router.
**Implementation Maturity**: The architecture is sound, but code is still being hardened. Not yet for managing billion-dollar portfolios solo.
## 📦 What You Get (MCP Server)
### Core Tools
| Tool | Purpose | Example |
|------|---------|---------|
| `rebalance` | Adjust portfolio to target allocation | "Shift to 60/30/10" |
| `swap` | Atomic token exchange | "Swap 10 ETH for USDC" |
| `provide_liquidity` | Deposit into Multiswap | "Add 50 ETH + $100k USDC" |
| `get_portfolio` | Fetch current state | "What's my current allocation?" |
| `estimate_gas` | Check execution costs | "How much gas for this trade?" |
### What Makes It Different
```
Generic MCP vs. CavalRe MCP
┌──────────────────┐ ┌─────────────────────────┐
│ "Swap tokens" │ │ "Swap tokens via │
│ → Call Uniswap │ │ atomic basket" │
│ → Hope for best │ │ │
│ ❌ No ledger │ │ → Validate ledger first │
│ ❌ No safety │ │ → Check constraints │
│ ❌ No audit │ │ → Execute atomically │
│ │ │ → Record immutably │
│ │ │ ✅ Deterministic │
│ │ │ ✅ Safe │
│ │ │ ✅ Auditable │
└──────────────────┘ └─────────────────────────┘
```
## 🎯 Target Users
### Who Should Use This?
✅ **AI research teams** building autonomous trading agents
✅ **DeFi protocol teams** needing institutional liquidity
✅ **Asset managers** with $10M+ portfolios
✅ **RWA platforms** requiring double-entry accounting
### Who Shouldn't
❌ **Retail traders** (use MetaMask + Uniswap directly)
❌ **Simple bot builders** (use a generic trading API)
❌ **Projects needing production stability** (we're v1.1, still hardening)
## 🚀 Getting Started (For Developers)
### Installation
```bash
# 1. Clone
git clone https://github.com/RedRobotKK/CavalRe_MCP.git
cd CavalRe_MCP
# 2. Setup
bash install.sh
# 3. Run tests (verify your setup)
npm test
# 4. Start the MCP server
npm run dev
# 5. Connect your LLM agent
# Your AI agent can now call CavalRe primitives safely
```
### Your First Agent
```python
# Pseudo-code: Connect Claude to CavalRe
from anthropic import Anthropic
client = Anthropic()
# Register CavalRe MCP tools
tools = [
{"name": "rebalance", "description": "Rebalance portfolio..."},
{"name": "swap", "description": "Execute atomic swap..."},
# ... more tools
]
# Run agent loop
response = client.messages.create(
model="claude-3-opus",
max_tokens=1024,
tools=tools,
messages=[{
"role": "user",
"content": "Rebalance my portfolio to 60% ETH, 30% stables, 10% alts"
}]
)
# CavalRe MCP safely executes whatever Claude decides
```
## 📚 Documentation
| Resource | Purpose |
|----------|---------|
| [PRIMITIVES.md](docs/PRIMITIVES.md) | All 6 primitives + execution strategies |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Deep dive into system design |
| [SECURITY.md](SECURITY.md) | Security audit + threat model |
| [EXAMPLES.md](docs/EXAMPLES.md) | Real agent examples |
| [CavalRe Core Docs](https://github.com/CavalRe/cavalre-contracts) | The underlying protocol |
## 🌟 The Vision
CavalRe is building the **liquidity layer for autonomous financial agents**.
Just like Stripe abstracts payments, CavalRe abstracts institutional DeFi execution. Your AI agent shouldn't worry about slippage, routing, or audit trails. That's our job.
```
Today: Agents + Generic APIs = Fragmented, risky execution
Tomorrow: Agents + CavalRe MCP = Safe, atomic, institutional-grade
```
## 💬 Community
- 🐙 [GitHub Issues](https://github.com/RedRobotKK/CavalRe_MCP/issues) - Bug reports
- 💬 [Discord](https://discord.gg/VA6MhZ8cVb) - Real-time support
- 🐦 [Twitter](https://twitter.com/TheCavalRe) - Updates
- 🔗 [CavalRe Core](https://github.com/CavalRe) - The protocol we're built on
## 📄 License
MIT - See [LICENSE](LICENSE)
**v1.1.0 | Institutional DeFi for AI Agents | Accounting-First • Atomic Execution • Zero-Custody**
