Skip to main content

​
Overview

The ouroborai MCP server exposes Arbitrum DeFi tools through the Model Context Protocol, a standard for connecting AI assistants to external capabilities. This lets you use ouroborai’s trading, lending, and portfolio tools directly from Claude Desktop, Cursor, or any MCP-compatible client. The server runs as a local stdio process and communicates with the AI client over stdin/stdout. No HTTP server or port binding is required.

​
Available tools

The MCP server provides 17 tools organized by function:
ToolDescription
arb_quoteGet a swap quote on Uniswap V3. Returns expected output, price impact, and fees without executing.
arb_tradeExecute a spot swap on Uniswap V3 or Camelot. Auto-selects the best route.
Parameters for arb_quote:
ParamTypeRequiredDescription
tokenInstringYesInput token address or symbol (USDC, WETH, ARB, WBTC)
tokenOutstringYesOutput token address or symbol
amountInstringYesHuman-readable amount (e.g., "100" for 100 USDC)
feeTiernumberNoFee tier: 100, 500, 3000, or 10000
Parameters for arb_trade:
ParamTypeRequiredDescription
tokenInstringYesInput token symbol or address
tokenOutstringYesOutput token symbol or address
amountInstringYesHuman-readable amount
slippageBpsnumberNoMax slippage in basis points (default: 50 = 0.5%)
ToolDescription
arb_perp_openOpen a leveraged perpetual position on GMX V2. Up to 100x on ETH, BTC, ARB, LINK.
arb_perp_closeClose an existing GMX V2 perpetual position.
arb_perp_positionsList all open perpetual positions with PnL and liquidation prices.
Parameters for arb_perp_open:
ParamTypeRequiredDescription
marketstringYesMarket pair: ETH/USDC, BTC/USDC, ARB/USDC, LINK/USDC
sidestringYeslong or short
collateralUsdcstringYesCollateral amount in USDC (e.g., "500")
leveragenumberYesLeverage multiplier (1-100)
ToolDescription
arb_lend_supplySupply an asset to Aave V3 on Arbitrum to earn yield.
arb_lend_borrowBorrow an asset from Aave V3 (variable rate). Requires supplied collateral.
arb_lend_healthGet Aave V3 health factor and position summary. Health above 1.0 is safe.
Parameters for arb_lend_supply / arb_lend_borrow:
ParamTypeRequiredDescription
assetstringYesAsset symbol: USDC, WETH, WBTC, ARB
amountstringYesHuman-readable amount
ToolDescription
arb_timeboost_statusCurrent express lane status: round number, controller address, and round end time.
arb_timeboost_bidBid for the express lane in the upcoming round. Winner gets 200ms transaction priority for 60 seconds.
Parameters for arb_timeboost_bid:
ParamTypeRequiredDescription
bidAmountEthstringYesBid amount in ETH (e.g., "0.001")
ToolDescription
arb_session_keyCreate a scoped session key for autonomous trading within defined limits.
arb_batchExecute multiple DeFi operations atomically in a single transaction.
Parameters for arb_session_key:
ParamTypeRequiredDescription
validForHoursnumberYesSession key lifetime in hours (max 72)
spendingLimitUsdcstringYesMax USDC spending limit
allowedProtocolsstring[]NoProtocols the key can interact with (uniswap, gmx, aave, pendle, camelot)
ToolDescription
arb_portfolioFull portfolio snapshot: wallet balances, Aave positions, GMX perpetuals, TimeBoost status.
arb_rwa_scanScan tokenized RWA stock contracts on Robinhood Chain. Search by symbol, get contract info, or view registry stats.
arb_alchemix_accountAlchemix V2 self-repaying loan account data: debt, collateral, supported tokens.
arb_prediction_searchSearch Polymarket prediction markets. Returns questions, outcome probabilities, and volume.
arb_install_skillInstall a new skill from a GitHub URL to extend agent capabilities.

​
Configuration

​
Claude Desktop

Add the server to your claude_desktop_config.json: 
{
  "mcpServers": {
    "arbitrum-agent": {
      "command": "node",
      "args": ["/path/to/arbitrum-agent/apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKey",
        "ARB_RPC_URL": "https://arb1.arbitrum.io/rpc",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
The PRIVATE_KEY controls the wallet used for all on-chain operations. Use a dedicated trading wallet, not your primary wallet. Never commit this value to version control.

​
Cursor

Add the server to your Cursor MCP settings (.cursor/mcp.json in your project root): 
{
  "mcpServers": {
    "arbitrum-agent": {
      "command": "node",
      "args": ["/path/to/arbitrum-agent/apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKey",
        "ARB_RPC_URL": "https://arb1.arbitrum.io/rpc"
      }
    }
  }
}

​
Claude Code

Add the server to your project’s .mcp.json: 
{
  "mcpServers": {
    "arbitrum-agent": {
      "command": "node",
      "args": ["apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKey",
        "ARB_RPC_URL": "https://arb1.arbitrum.io/rpc"
      }
    }
  }
}

​
Environment variables

VariableRequiredDescription
PRIVATE_KEYYesHex-encoded private key for the agent wallet (e.g., 0xabc...)
ARB_RPC_URLNoArbitrum One RPC endpoint. Defaults to the public RPC if not set.
ANTHROPIC_API_KEYNoOnly needed if running the API server alongside the MCP server. Not required for MCP tool execution.

​
Building from source

The MCP server must be compiled before use: 
cd apps/mcp-server
bun run build
The build produces dist/index.js which is the entry point for MCP clients. Dependencies like @zerodev/*, permissionless, and tslib must be marked as external during the build.
The build order matters in the monorepo. Build the SDK package first, then adapters, skills, timeboost, and smart-account packages, and finally the MCP server.

​
Tool usage examples

Here are example interactions showing how Claude uses the MCP tools:
User: Swap 100 USDC for ETHClaude calls: arb_quote with { tokenIn: "USDC", tokenOut: "WETH", amountIn: "100" }Tool returns:
{
  "amountOut": "0.031200",
  "priceImpact": "0.05%",
  "fee": "0.300000",
  "route": ["USDC", "WETH"]
}
Claude calls: arb_trade with { tokenIn: "USDC", tokenOut: "WETH", amountIn: "100" }Tool returns:
{ "txHash": "0xabc...", "status": "submitted" }
User: What is my Aave health factor?Claude calls: arb_lend_health with {}Tool returns:
{
  "healthFactor": "2.4500",
  "status": "safe",
  "totalCollateralUsd": "5000.000000",
  "totalDebtUsd": "1000.000000",
  "availableBorrowsUsd": "2500.000000",
  "ltv": "50.0%"
}
User: Open a 10x long on ETH/USDC with 500 USDC collateralClaude calls: arb_perp_open with:
{
  "market": "ETH/USDC",
  "side": "long",
  "collateralUsdc": "500",
  "leverage": 10
}
Tool returns:
{
  "txHash": "0xdef...",
  "status": "order submitted to GMX keepers"
}
User: Show me my portfolioClaude calls: arb_portfolio with {}Tool returns:
{
  "wallet": "0xYourAddress",
  "balances": {
    "eth": "1.250000",
    "usdc": "3200.000000"
  },
  "aave": {
    "healthFactor": "2.4500",
    "collateral": "5000.000000",
    "debt": "1000.000000"
  },
  "gmxPositions": 1,
  "timeboost": {
    "isController": false
  }
}

​
Token resolution

Tools that accept token symbols resolve them to on-chain addresses automatically. Supported symbols:
SymbolAddress
USDC0xaf88d065e77c8cc2239327c5edb3a432268e5831
WETH / ETH0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
ARB0x912CE59144191C1204E64559FE8253a0e49E6548
WBTC0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f
PENDLEPendle token contract on Arbitrum
You can also pass full contract addresses (starting with 0x) instead of symbols.

​
Architecture

The MCP server is a standalone stdio process that:
  1. Receives tool call requests from the AI client over stdin
  2. Initializes a ArbWallet instance from the PRIVATE_KEY environment variable
  3. Dispatches tool calls to the appropriate protocol adapter (Uniswap, GMX, Aave, etc.)
  4. Returns JSON results over stdout
The server uses the @modelcontextprotocol/sdk package with StdioServerTransport. It does not open any network ports or accept HTTP connections — all communication happens through the parent process’s stdio pipes.