MCP Server

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:

Trading

Tool	Description
`arb_quote`	Get a swap quote on Uniswap V3. Returns expected output, price impact, and fees without executing.
`arb_trade`	Execute a spot swap on Uniswap V3 or Camelot. Auto-selects the best route.

Parameters for arb_quote:

Param	Type	Required	Description
`tokenIn`	string	Yes	Input token address or symbol (USDC, WETH, ARB, WBTC)
`tokenOut`	string	Yes	Output token address or symbol
`amountIn`	string	Yes	Human-readable amount (e.g., `"100"` for 100 USDC)
`feeTier`	number	No	Fee tier: 100, 500, 3000, or 10000

Parameters for arb_trade:

Param	Type	Required	Description
`tokenIn`	string	Yes	Input token symbol or address
`tokenOut`	string	Yes	Output token symbol or address
`amountIn`	string	Yes	Human-readable amount
`slippageBps`	number	No	Max slippage in basis points (default: 50 = 0.5%)

Perpetuals

Tool	Description
`arb_perp_open`	Open a leveraged perpetual position on GMX V2. Up to 100x on ETH, BTC, ARB, LINK.
`arb_perp_close`	Close an existing GMX V2 perpetual position.
`arb_perp_positions`	List all open perpetual positions with PnL and liquidation prices.

Parameters for arb_perp_open:

Param	Type	Required	Description
`market`	string	Yes	Market pair: `ETH/USDC`, `BTC/USDC`, `ARB/USDC`, `LINK/USDC`
`side`	string	Yes	`long` or `short`
`collateralUsdc`	string	Yes	Collateral amount in USDC (e.g., `"500"`)
`leverage`	number	Yes	Leverage multiplier (1-100)

Lending

Tool	Description
`arb_lend_supply`	Supply an asset to Aave V3 on Arbitrum to earn yield.
`arb_lend_borrow`	Borrow an asset from Aave V3 (variable rate). Requires supplied collateral.
`arb_lend_health`	Get Aave V3 health factor and position summary. Health above 1.0 is safe.

Parameters for arb_lend_supply / arb_lend_borrow:

Param	Type	Required	Description
`asset`	string	Yes	Asset symbol: USDC, WETH, WBTC, ARB
`amount`	string	Yes	Human-readable amount

TimeBoost

Tool	Description
`arb_timeboost_status`	Current express lane status: round number, controller address, and round end time.
`arb_timeboost_bid`	Bid for the express lane in the upcoming round. Winner gets 200ms transaction priority for 60 seconds.

Parameters for arb_timeboost_bid:

Param	Type	Required	Description
`bidAmountEth`	string	Yes	Bid amount in ETH (e.g., `"0.001"`)

Account management

Tool	Description
`arb_session_key`	Create a scoped session key for autonomous trading within defined limits.
`arb_batch`	Execute multiple DeFi operations atomically in a single transaction.

Parameters for arb_session_key:

Param	Type	Required	Description
`validForHours`	number	Yes	Session key lifetime in hours (max 72)
`spendingLimitUsdc`	string	Yes	Max USDC spending limit
`allowedProtocols`	string[]	No	Protocols the key can interact with (uniswap, gmx, aave, pendle, camelot)

Portfolio and data

Tool	Description
`arb_portfolio`	Full portfolio snapshot: wallet balances, Aave positions, GMX perpetuals, TimeBoost status.
`arb_rwa_scan`	Scan tokenized RWA stock contracts on Robinhood Chain. Search by symbol, get contract info, or view registry stats.
`arb_alchemix_account`	Alchemix V2 self-repaying loan account data: debt, collateral, supported tokens.
`arb_prediction_search`	Search Polymarket prediction markets. Returns questions, outcome probabilities, and volume.
`arb_install_skill`	Install 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

Variable	Required	Description
`PRIVATE_KEY`	Yes	Hex-encoded private key for the agent wallet (e.g., `0xabc...`)
`ARB_RPC_URL`	No	Arbitrum One RPC endpoint. Defaults to the public RPC if not set.
`ANTHROPIC_API_KEY`	No	Only 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:

Swap tokens

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" }

Check lending health

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%"
}

Open a perpetual position

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"
}

Full portfolio view

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:

Symbol	Address
`USDC`	`0xaf88d065e77c8cc2239327c5edb3a432268e5831`
`WETH` / `ETH`	`0x82aF49447D8a07e3bd95BD0d56f35241523fBab1`
`ARB`	`0x912CE59144191C1204E64559FE8253a0e49E6548`
`WBTC`	`0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f`
`PENDLE`	Pendle 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:

Receives tool call requests from the AI client over stdin
Initializes a ArbWallet instance from the PRIVATE_KEY environment variable
Dispatches tool calls to the appropriate protocol adapter (Uniswap, GMX, Aave, etc.)
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.

Getting Started

Agent API

Features

Contracts

Bots

Guides

Overview

Available tools

Configuration

Claude Desktop

Cursor

Claude Code

Environment variables

Building from source

Tool usage examples

Token resolution

Architecture

​Overview

​Available tools

​Configuration

​Claude Desktop

​Cursor

​Claude Code

​Environment variables

​Building from source

​Tool usage examples

​Token resolution

​Architecture

Overview

Available tools

Configuration

Claude Desktop

Cursor

Claude Code

Environment variables

Building from source

Tool usage examples

Token resolution

Architecture