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

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

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)

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.