Katana

You can run a Katana MCP Server to bridge assets, manage Yearn vaults, and perform SushiSwap swaps across supported networks. This MCP server acts as a bridge between your AI assistant and on-chain actions, enabling automated, secure interactions like cross-chain deposits, vault deposits/withdrawals, and real-time swap quotes from SushiSwap.

How to use

You will connect your MCP-compatible AI assistant to the Katana MCP Server using the provided MCP configuration. Once connected, you can issue high-level intents such as bridging assets from Ethereum or Polygon into Katana, querying your token balances, depositing into Yearn vaults, withdrawing from vaults, and getting real-time swap quotes to execute token swaps. Your assistant can orchestrate these actions while applying built-in safety checks like slippage protection and gas estimation.

Typical usage patterns include: bridging assets from a source network to Katana, optionally obtaining a deposit address automatically; querying balances to review holdings; managing vault positions by depositing or withdrawing; and requesting swap quotes or performing swaps on SushiSwap with configurable slippage. Explicitly provide your wallet private key via the configured environment variable to enable authorized actions.

How to install

Prerequisites: you need Node.js 18.0.0 or higher and a package manager such as npm or pnpm. You also need a wallet private key with funds on supported networks.

# Step 1: Clone the server repository
git clone https://github.com/yourusername/katana-mcp-server.git
cd katana-mcp-server

# Step 2: Install dependencies using your preferred package manager
pnpm install
# or
npm install

# Step 3: Create an environment file with your private key
# Do not commit this file
echo 'WALLET_PRIVATE_KEY=your_private_key_here' > .env

# Step 4: Build the project
pnpm run build
# or
npm run build

# Step 5: Start the server
pnpm run start
# or
npm run start

Configuration and setup notes

Add the MCP server configuration to your AI assistant so it can communicate with Katana. The following MCP configuration shows how to run the server using npx with the required environment variable.

{
  "mcpServers": {
    "katana-mcp": {
      "command": "npx",
      "args": ["katana-mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

Security and error handling

Expect comprehensive error handling for common issues such as insufficient balance, network failures, and slippage. The server performs private key management via secure environment variables, pre-execution simulation, and gas estimation with safety margins to reduce failed transactions.

If issues arise, verify that your wallet has sufficient funds, the correct minimum deposit amounts are met for the source network, and that your slippage settings are appropriate for the market conditions.

Troubleshooting

Common problems include missing WALLET_PRIVATE_KEY in the environment, insufficient balance for gas, and bridge or vault operation failures. Ensure your .env file is present and correctly loaded, check your network balances, and review minimum deposits for each supported network.

Notes

You will manage private keys securely via environment variables and rely on automatic gas estimation and slippage protection to protect your transactions. The server exposes tools to bridge assets, get token balances, manage Yearn vaults, and interact with SushiSwap, all orchestrated through your MCP-enabled assistant.

Examples

Bridge 100 USDC from Ethereum to Katana using your assistant, then check your Katana token balances and deposit 1000 USDC into the USDC Yearn vault.

Available tools

bridgeAssets

Bridge tokens from supported chains to the Katana network using a single command with asset, chain, and amount parameters.

getTokenBalances

Query token balances across Katana assets for a given wallet address.

getYearnVaultInfo

Retrieve detailed information about available Yearn vaults on Katana.

depositToYearnVault

Deposit specified token amounts into a selected Yearn vault.

withdrawFromYearnVault

Withdraw funds from a Yearn vault position, either as assets or shares.

getUserYearnPositions

View current Yearn vault positions and expected yields for the user.

getSushiQuote

Obtain a swap quote for token pairs on SushiSwap with a defined max slippage.

executeSushiSwap

Execute a token swap on SushiSwap with a configured slippage tolerance.