How do I use CavalRe MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CavalRe MCP Server Rebalance to 60% ETH 30% USDC 10% MATIC" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Version Security Tests Maturity

📖 Docs • 🏗️ Architecture • 🔐 Security • 🌊 CavalRe Core • 💬 Discord

🤖 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: 42}    │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└────────────────────────┬─────────────────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│                    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
    • Ledger: ✅ Balanced
    • Execution: ✅ Atomic
    • Gas: 142 gwei
    • Slippage: 0.38%

[9] SLEEP
    Agent monitored everything. Fund 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 & heartbeat - Discover and connect to agents
🔐 Secure update mechanism - 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

# 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

# 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	All 6 primitives + execution strategies
ARCHITECTURE.md	Deep dive into system design
SECURITY.md	Security audit + threat model
EXAMPLES.md	Real agent examples
CavalRe Core Docs	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 - Bug reports
💬 Discord - Real-time support
🐦 Twitter - Updates
🔗 CavalRe Core - The protocol we're built on

📄 License

MIT - See LICENSE

v1.1.0 | Institutional DeFi for AI Agents | Accounting-First • Atomic Execution • Zero-Custody

CavalRe MCP Server