EXPERMINTAL MODE ONLY

Fluid MCP Server

A production-ready Model Context Protocol (MCP) server that enables AI agents to interact with the Fluid DeFi Protocol across all supported chains.

Fluid is a next-generation DeFi protocol by Instadapp that unifies lending, borrowing, and DEX trading into a single capital-efficient liquidity layer.

Supported Chains

Chain	Chain ID	Protocols
Ethereum	1	Liquidity, Lending, Vault, DEX
Arbitrum	42161	Liquidity, Lending, Vault, DEX
Base	8453	Liquidity, Lending, Vault, DEX
Polygon	137	Liquidity, Lending, Vault, DEX

Quick Start

Install & Run

# Install globally
npm install -g fluid-mcp-server

# Or run directly with npx
npx fluid-mcp-server

Add to Claude Desktop

Add to your Claude Desktop config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fluid": {
      "command": "npx",
      "args": ["fluid-mcp-server"]
    }
  }
}

Add to Claude Code

claude mcp add fluid -- npx fluid-mcp-server

Build from Source

git clone https://github.com/ahmadmardeni1/fluid-mcp-server.git
cd fluid-mcp-server
npm install
npm run build
npm start

Architecture

graph TB
    subgraph "AI Agent Layer"
        Agent[AI Agent / LLM]
        MCP[MCP Client]
    end

    subgraph "Fluid MCP Server"
        Server[MCP Server Entry Point]

        subgraph "READ Tools"
            LR[Liquidity Read]
            LendR[Lending Read]
            VR[Vault Read]
            DR[DEX Read]
        end

        subgraph "WRITE Tools"
            LendW[Lending Write]
            VW[Vault Write]
            DW[DEX Write]
        end

        Config[Chain Config]
        ABIs[ABI Definitions]
        Provider[Provider Manager]
    end

    subgraph "Fluid Protocol (On-Chain)"
        LL[Liquidity Layer]
        LP[Lending Protocol / fTokens]
        VP[Vault Protocol]
        DEX[DEX Protocol]

        subgraph "Resolvers"
            LiqR[LiquidityResolver]
            LendRes[LendingResolver]
            VaultRes[VaultResolver]
            DexRes[DexReservesResolver]
        end
    end

    Agent --> MCP
    MCP --> Server
    Server --> LR & LendR & VR & DR
    Server --> LendW & VW & DW
    LR & LendR & VR & DR --> Provider
    LendW & VW & DW --> Provider
    Provider --> Config & ABIs
    Provider --> LiqR & LendRes & VaultRes & DexRes
    LiqR --> LL
    LendRes --> LP
    VaultRes --> VP
    DexRes --> DEX

Tool Reference

READ Tools (No wallet required)

These tools query on-chain data through Fluid's resolver contracts. They are completely read-only and require no wallet or private key.

Liquidity Layer

Tool	Description
fluid_get_listed_tokens	List all tokens in the Liquidity Layer
fluid_get_token_rates	Get supply/borrow rates for a specific token
fluid_get_all_tokens_data	Dashboard view of all tokens with rates and TVL
fluid_get_user_supply	Query a user's supply position for a token
fluid_get_user_borrow	Query a user's borrow position for a token
fluid_get_revenue	Get protocol revenue for a token

Lending Protocol (fTokens)

Tool	Description
fluid_get_all_ftokens	List all fToken addresses
fluid_get_ftoken_details	Get details for a specific fToken (rates, TVL, asset)
fluid_get_all_ftokens_details	Dashboard view of all fTokens
fluid_get_user_lending_position	Get user's position in an fToken pool
fluid_get_ftoken_rewards	Get reward program info for an fToken

Vault Protocol

Tool	Description
fluid_get_all_vaults	List all vault addresses
fluid_get_vault_data	Get comprehensive vault data (rates, limits, totals)
fluid_get_all_vaults_data	Dashboard view of all vaults
fluid_get_vault_position	Get a position by NFT ID
fluid_get_user_vault_positions	Get all positions owned by a user
fluid_get_liquidations	Get available liquidation opportunities

DEX Protocol

Tool	Description
fluid_get_dex_pools	List all DEX pool addresses
fluid_get_pool_reserves	Get reserves for a specific pool
fluid_get_all_pools_reserves	Get reserves for all pools
fluid_get_pool_adjusted_reserves	Get adjusted reserves (for swap math)
fluid_estimate_swap_in	Estimate output for a given input
fluid_estimate_swap_out	Estimate required input for a desired output

WRITE Tools (Wallet required)

These tools build unsigned transaction data. The calling agent must sign and broadcast the transaction using the user's wallet.

Lending Operations

Tool	Description
fluid_build_lending_deposit	Build deposit tx (ERC20 → fToken)
fluid_build_lending_deposit_native	Build native ETH deposit tx
fluid_build_lending_withdraw	Build withdrawal tx (fToken → asset)
fluid_build_lending_redeem	Build redeem tx (burn shares for assets)
fluid_build_token_approve	Build ERC20 approval tx

Vault Operations

Tool	Description
fluid_build_vault_open	Open new vault position (deposit + optional borrow)
fluid_build_vault_operate	Modify existing position (add/remove collateral, borrow/repay)
fluid_build_vault_close	Close position (repay all + withdraw all)

DEX Operations

Tool	Description
fluid_build_swap_exact_input	Build swap tx with exact input amount
fluid_build_swap_exact_output	Build swap tx for exact output amount

Protocol Flow Diagrams

Lending Flow (Deposit & Earn)

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Chain as Blockchain
    participant fToken as fToken Contract
    participant LL as Liquidity Layer

    Note over Agent,LL: Step 1: Research
    Agent->>MCP: fluid_get_all_ftokens_details(chain)
    MCP->>Chain: LendingResolver.getAllFTokensDetails()
    Chain-->>MCP: [fToken details with rates]
    MCP-->>Agent: Best APY opportunities

    Note over Agent,LL: Step 2: Approve (if ERC20)
    Agent->>MCP: fluid_build_token_approve(token, fToken)
    MCP-->>Agent: Unsigned approval tx
    Agent->>Chain: Sign & send approval

    Note over Agent,LL: Step 3: Deposit
    Agent->>MCP: fluid_build_lending_deposit(fToken, amount, receiver)
    MCP-->>Agent: Unsigned deposit tx + preview shares
    Agent->>Chain: Sign & send deposit tx
    Chain->>fToken: deposit(assets, receiver)
    fToken->>LL: Supply to Liquidity Layer
    fToken-->>Agent: fToken shares minted

Vault Flow (Borrow Against Collateral)

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Chain as Blockchain
    participant Vault as Vault Contract
    participant LL as Liquidity Layer

    Note over Agent,LL: Step 1: Find a vault
    Agent->>MCP: fluid_get_all_vaults_data(chain)
    MCP->>Chain: VaultResolver.getAllVaultsEntireData()
    Chain-->>MCP: [All vaults with rates, limits, LTV]
    MCP-->>Agent: Available vaults + collateral factors

    Note over Agent,LL: Step 2: Open position
    Agent->>MCP: fluid_build_vault_open(vault, collateral, borrow, receiver)
    MCP-->>Agent: Unsigned operate() tx
    Agent->>Chain: Sign & send tx
    Chain->>Vault: operate(0, +col, +debt, to)
    Vault->>LL: Deposit collateral + borrow from Liquidity
    Vault-->>Agent: NFT minted (position ID)

    Note over Agent,LL: Step 3: Monitor health
    Agent->>MCP: fluid_get_vault_position(nftId)
    MCP->>Chain: VaultResolver.positionByNftId()
    Chain-->>MCP: Position data
    MCP-->>Agent: Supply, borrow, LTV, health

    Note over Agent,LL: Step 4: Repay & close
    Agent->>MCP: fluid_build_vault_close(vault, nftId, receiver)
    MCP-->>Agent: Unsigned close tx
    Agent->>Chain: Sign & send tx
    Chain->>Vault: operate(nftId, MIN, MIN, to)
    Vault-->>Agent: All collateral returned

DEX Swap Flow

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Chain as Blockchain
    participant Pool as DEX Pool
    participant Res as DexReservesResolver

    Note over Agent,Res: Step 1: Discover pools
    Agent->>MCP: fluid_get_all_pools_reserves(chain)
    MCP->>Chain: DexResolver.getAllPoolsReserves()
    Chain-->>MCP: [All pools with token pairs & reserves]
    MCP-->>Agent: Available trading pairs

    Note over Agent,Res: Step 2: Get quote
    Agent->>MCP: fluid_estimate_swap_in(pool, direction, amountIn)
    MCP->>Chain: Fetch adjusted reserves + estimate
    Chain-->>MCP: Estimated output
    MCP-->>Agent: Quote with price impact

    Note over Agent,Res: Step 3: Execute swap
    Agent->>MCP: fluid_build_swap_exact_input(pool, direction, amountIn, slippage, receiver)
    MCP->>Chain: Fetch reserves + calculate minOutput
    MCP-->>Agent: Unsigned swap tx with slippage protection
    Agent->>Chain: Sign & send swap tx
    Chain->>Pool: swapIn(direction, amountIn, minOut, to)
    Pool-->>Agent: Output tokens received

Transaction Signing

This MCP server follows a non-custodial design. Write tools return unsigned transaction data — the JSON response contains:

{
  "chain": "ethereum",
  "action": "deposit",
  "to": "0x...",       // Contract to call
  "data": "0x...",     // Encoded calldata
  "value": "0",        // ETH value to send (wei)
  "description": "...",
  "note": "..."
}

The calling agent is responsible for:

1. Connecting to the user's wallet (e.g., via ethers.js, web3.js, or wallet SDK)
2. Signing the transaction with the user's private key
3. Broadcasting the signed transaction to the blockchain
4. Monitoring the transaction for confirmation

Example (ethers.js v6):

import { ethers } from "ethers";

// After receiving tx data from MCP tool:
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
const tx = await wallet.sendTransaction({
  to: toolResult.to,
  data: toolResult.data,
  value: BigInt(toolResult.value),
});
const receipt = await tx.wait();

Custom RPC URLs

Every tool accepts an optional rpc_url parameter to use a custom RPC endpoint instead of the default public one. This is recommended for production use to avoid rate limits.

{
  "chain": "ethereum",
  "rpc_url": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
}

Environment Variables

Variable	Description	Default
FLUID_RPC_ETHEREUM	Custom RPC for Ethereum	Public RPC
FLUID_RPC_ARBITRUM	Custom RPC for Arbitrum	Public RPC
FLUID_RPC_BASE	Custom RPC for Base	Public RPC
FLUID_RPC_POLYGON	Custom RPC for Polygon	Public RPC

Resources

The server exposes two MCP resources:

• fluid://chains — Supported chains and available protocols per chain
• fluid://overview — Protocol architecture overview with links

Prompts

Three built-in prompts guide agents through common workflows:

• analyze-lending-rates — Find the best lending yield opportunities
• check-vault-health — Assess a vault position's health and risk
• find-swap-route — Find optimal swap routes on Fluid DEX

Project Structure

fluid-mcp-server/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── config/
│   │   └── chains.ts            # Multi-chain contract addresses
│   ├── abis/
│   │   └── index.ts             # Minimal ABI definitions
│   ├── tools/
│   │   ├── index.ts             # Tool registry
│   │   ├── liquidity-read.ts    # Liquidity Layer queries
│   │   ├── lending-read.ts      # fToken lending queries
│   │   ├── vault-read.ts        # Vault protocol queries
│   │   ├── dex-read.ts          # DEX pool queries + swap estimates
│   │   ├── lending-write.ts     # Lending transaction builders
│   │   ├── vault-write.ts       # Vault transaction builders
│   │   └── dex-write.ts         # DEX swap transaction builders
│   └── utils/
│       ├── provider.ts          # Ethers.js provider management
│       └── formatting.ts        # Data formatting utilities
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

Testing & Example Tool Calls

You can exercise the MCP server directly over stdio using raw JSON‑RPC.

From the project root (after npm run build):

# 1) List all fTokens on Ethereum
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"fluid_get_all_ftokens","arguments":{"chain":"ethereum"}}}' \
  | node dist/index.js

# 2) Get detailed info for a specific fToken (fUSDC on Ethereum)
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fluid_get_ftoken_details","arguments":{"chain":"ethereum","ftoken_address":"0x9Fb7b4477576Fe5B32be4C1843aFB1e55F251B33"}}}' \
  | node dist/index.js

# 3) Build an unsigned deposit tx into fUSDC (100 USDC, 6 decimals)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fluid_build_lending_deposit","arguments":{"chain":"ethereum","ftoken_address":"0x9Fb7b4477576Fe5B32be4C1843aFB1e55F251B33","amount":"100000000","receiver":"0xYOUR_ADDRESS"}}}' \
  | node dist/index.js

# 4) List all vaults on Ethereum with their types (T1–T4)
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"fluid_get_all_vaults","arguments":{"chain":"ethereum"}}}' \
  | node dist/index.js

# 5) Build an unsigned Vault T1 operate() tx (open position)
# Example: ETH/GHO T1 vault on Ethereum
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"fluid_build_vault_t1_operate","arguments":{"chain":"ethereum","vault_address":"0xD9A7Dcdc57C6e44f00740dC73664fA456B983669","nft_id":0,"new_col":"100000000000000000","new_debt":"200000000000000000000","receiver":"0xYOUR_ADDRESS"}}}' \
  | node dist/index.js

Each call returns a JSON‑RPC response where result.content[0].text contains a JSON payload (either on‑chain data or an unsigned transaction description).

Contract Address Updates

Fluid's resolver contracts are periodically redeployed as the protocol evolves. The addresses in src/config/chains.ts are accurate as of the build date.

To get the latest addresses, check:

• Fluid deployments.md
• Fluid Technical Docs

References

• Fluid Protocol
• Fluid Technical Docs
• Fluid Contracts (GitHub)
• Fluid Governance
• MCP Specification
• MCP TypeScript SDK

License

MIT