kaskad-mcp

MCP (Model Context Protocol) server for Kaskad Protocol — reads live on-chain state from the Igra Galleon Testnet, executes transactions, and exposes tokenomics data via 11 tools.

Tools

Tool	Description
getMarkets	Live APY, utilization, liquidity for all active reserves
getPosition	Wallet collateral, debt, health factor, supplied/borrowed positions, staking balance
getGovernanceParams	Live DAO-voted parameters from KaskadGovernor (emission split, eligibility thresholds, treasury ratios)
getEmissions	KSKD emission state: epoch, vault depletion, supplier/borrower split, TWAL TVL
getUserRewards	Claimable KSKD rewards for a wallet address
getProtocolInfo	Static metadata + full AGENTS.md integration guide
getHistory	Subgraph data: liquidations, APY snapshots, user transaction history
supply	Supply an asset into the lending pool
borrow	Borrow an asset against collateral
repay	Repay outstanding debt
withdraw	Withdraw supplied assets

Quick Start

npm install
npm run build
npm test        # 19 unit tests (pure functions, no network)
node dist/index.js

Wallet Setup

Security — read before proceeding

The MCP server requires a private key to sign transactions. Always use a dedicated testnet wallet with no real funds. Never use a wallet that holds mainnet assets.

Never commit your private key to git. The credentials/ directory is gitignored.

The server requires a wallet private key to sign transactions. Use MCP_WALLET_KEY — it is the only recommended method.

Recommended — Environment variable

export MCP_WALLET_KEY=0xYOUR_TESTNET_PRIVATE_KEY
node dist/index.js

For MCP clients (Claude Desktop, OpenClaw, etc.), inject it via the env block in your client config (see MCP Client Config section below). The key never touches the filesystem.

Why not wallet.json? The server also supports credentials/wallet.json and ~/.kaskad-mcp/wallet.json as fallback paths for local development convenience. However, Anton (SC Architect) flagged these as an unnecessary attack surface — file-based key storage introduces git-commit risk, filesystem exposure, and misconfigured permission vectors. Do not use wallet.json in any shared, CI, or production-adjacent environment. If you must use a file locally, ensure credentials/ stays gitignored (it is by default) and restrict file permissions (chmod 600).

Trust boundary: The server enforces a minimum 100 iKAS reserve in the wallet at all times (to cover gas fees).

MCP Client Config

Add to your MCP client (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "kaskad": {
      "command": "node",
      "args": ["/path/to/kaskad-mcp/dist/index.js"],
      "env": {
        "MCP_WALLET_KEY": "0xYOUR_PRIVATE_KEY"
      }
    }
  }
}

Network

Property	Value
Chain ID	38836
Network	Igra Galleon Testnet
RPC	https://galleon-testnet.igralabs.com:8545
Explorer	https://explorer.galleon-testnet.igralabs.com
dApp	https://testnet.kaskad.live

Gas note: Igra Galleon requires minimum 2000 Gwei gas price. eth_estimateGas underestimates — all transactions use static gasLimit: 1_700_000n.

Contract Addresses (current deploy)

Contract	Address
Pool	0xA1D84fc43f7F2D803a2d64dbBa4A90A9A79E3F24
PoolAddressesProvider	0x9DB9797733FE5F734724Aa05D29Fa39563563Af5
PriceOracle	0xc1198A9d400306a0406fD3E3Ad67140b3D059f48
UIPoolDataProvider	0xbe38809914b552f295cD3e8dF2e77b3DA69cBC8b
RewardsController	0x0eB9dc7DD4eDc2226a20093Ca0515D84b7529468
ActivityTracker	0xa11FbfB7E69c3D8443335d30c5E6271bEE78b128
EmissionManager	0xcbcb1c3be7f32bf718b702f7b1700c36058edd8b
EmissionVault	0x18E5d69862E088B1ca326ACf48615875DF1763Af
KaskadGovernor	0xE89b59a211C4645150830Bc63c112d01eE47e888
stKSKD Vault	0xbA98cd5cC5E99058834072B3428de126b433d594
WrappedTokenGateway	0xaeb50b9b0340f760ab7c17eafcde90971083b4f9

Token	Address
USDC	0x32F59763c4b7F385DFC1DBB07742DaD4eeEccdb2
WETH	0xB4129cEBD85bDEcdD775f539Ec8387619a0f1FAC
WBTC	0x9dAc4c79bE2C541BE3584CE5244F3942554D6355
IGRA	0x04443457b050BBaa195bb71Ef6CCDb519CcB1f0f
WIKAS (iKAS)	0xA7CEd4eFE5C3aE0e5C26735559A77b1e38950a14
KSKD	0x2d17780a59044D49FeEf0AA9cEaB1B6e3161aFf7

Architecture

src/
├── abi/              # ABI JSON fragments from Foundry artifacts
├── contracts.ts      # Addresses, token registry, dead pool list
├── rpc.ts            # Raw JSON-RPC client (fetch-based, no ethers Provider)
├── typed-contracts.ts # Typed wrappers (Pool, Oracle, ERC20, Governor, Rewards, etc.)
├── index.ts          # MCP server + health HTTP endpoint
└── tools/
    ├── getMarkets.ts
    ├── getPosition.ts
    ├── getGovernanceParams.ts
    ├── getTokenomics.ts     # getEmissions + getUserRewards
    ├── getHistory.ts        # Subgraph queries
    ├── getProtocolInfo.ts
    └── executeTransaction.ts # supply/borrow/repay/withdraw

Maintenance Notes

• APY formula: currentLiquidityRate from getReserveData is in RAY (1e27). rate / 1e25 = APY%. Do NOT multiply by seconds_per_year.
• Dead pools: 7 deprecated reserve addresses from prior deploys are filtered from all output.
• iKAS: Native gas token. Balance via provider.getBalance(), not ERC20. WIKAS is the wrapped form used by the pool.
• Address updates: After testnet redeploy, re-extract from dApp bundle (/assets/index-*.js) and update src/contracts.ts.