Configure MCP

The ouroborai MCP (Model Context Protocol) server exposes DeFi tools directly in your AI coding environment. This lets Claude Code, Claude Desktop, or Cursor execute swaps, manage positions, and query portfolio data without switching to a browser.

Available Tools

The MCP server exposes these tools:

Tool	Description
`arb_quote`	Get swap quote without executing
`arb_trade`	Execute spot swap (Uniswap V3 / Camelot)
`arb_perp_open`	Open GMX V2 leveraged position
`arb_perp_close`	Close GMX V2 position
`arb_perp_positions`	List open perpetual positions
`arb_lend_supply`	Supply asset to Aave V3
`arb_lend_borrow`	Borrow from Aave V3
`arb_lend_health`	Get Aave health factor
`arb_timeboost_status`	Express lane status
`arb_timeboost_bid`	Bid for express lane round
`arb_session_key`	Create scoped trading session key
`arb_batch`	Atomic multi-step DeFi execution
`arb_portfolio`	Full portfolio snapshot
`arb_rwa_scan`	Scan RWA stocks on Robinhood Chain
`arb_prediction_search`	Search Polymarket prediction markets
`arb_alchemix_account`	Alchemix V2 self-repaying loan data
`arb_install_skill`	Install a skill from GitHub URL

Setup

First, build the MCP server:

cd apps/mcp-server
bun run build

This produces dist/index.js which runs as a stdio-based MCP server.

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "arbitrum-agent": {
      "command": "node",
      "args": ["/absolute/path/to/apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "ARB_RPC_URL": "https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY"
      }
    }
  }
}

// .cursor/mcp.json in your project root

{
  "mcpServers": {
    "arbitrum-agent": {
      "command": "node",
      "args": ["./apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "ARB_RPC_URL": "https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY"
      }
    }
  }
}

// .mcp.json in your project root

{
  "mcpServers": {
    "arbitrum-agent": {
      "command": "node",
      "args": ["./apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "ARB_RPC_URL": "https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY"
      }
    }
  }
}

// .vscode/mcp.json

{
  "servers": {
    "arbitrum-agent": {
      "type": "stdio",
      "command": "node",
      "args": ["./apps/mcp-server/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "ARB_RPC_URL": "https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY"
      }
    }
  }
}

The MCP configuration file contains your private key in plaintext. Do NOT commit .mcp.json or claude_desktop_config.json to version control. The repository .gitignore excludes .mcp.json by default.

Usage Examples

After configuration, you can interact with the tools through natural language in your AI client:

"Get me a quote for swapping 500 USDC to ETH"
→ Calls arb_quote with tokenIn=USDC, tokenOut=ETH, amountIn=500

"Open a 10x long on ETH with 200 USDC collateral"
→ Calls arb_perp_open with market=ETH/USDC, side=long, leverage=10

"What's my portfolio?"
→ Calls arb_portfolio, returns balances + Aave + GMX positions

"Check my Aave health factor"
→ Calls arb_lend_health, returns health factor and status

Security Considerations

The MCP server has full access to the configured wallet. Any tool call that modifies on-chain state (trades, lending, perpetuals) will execute using the private key in the environment.

To limit risk:

Use a dedicated hot wallet with limited funds
Set up session keys via arb_session_key with spending limits and protocol restrictions
Review tool calls before confirming execution in your AI client
Consider using Arbitrum Sepolia for testing before mainnet

Troubleshooting

MCP server not detected

Ensure the command path points to a valid node binary and the args path points to the built dist/index.js. Try running the command manually to check for errors:

PRIVATE_KEY=0x... ARB_RPC_URL=https://... \
  node apps/mcp-server/dist/index.js

The server should start without output (it communicates via stdio).

Tool calls returning errors

Common causes:

PRIVATE_KEY not set or invalid format (must start with 0x)
ARB_RPC_URL unreachable or rate-limited
Insufficient ETH for gas or USDC for trades
Token symbol not recognized (use: USDC, WETH, ETH, ARB, WBTC, PENDLE)

Getting Started

Agent API

Features

Contracts

Bots

Guides

Available Tools

Setup

Usage Examples

Security Considerations

Troubleshooting

​Available Tools

​Setup

​Usage Examples

​Security Considerations

​Troubleshooting

Available Tools

Setup

Usage Examples

Security Considerations

Troubleshooting