> ## Documentation Index
> Fetch the complete documentation index at: https://ouroborai.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure MCP

> Connect ouroborai tools to Claude Desktop or Cursor

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:

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
cd apps/mcp-server
bun run build
```

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

<CodeGroup>
  ```json Claude Desktop theme={"theme":{"light":"dracula","dark":"dracula"}}
  // ~/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"
        }
      }
    }
  }
  ```

  ```json Cursor theme={"theme":{"light":"dracula","dark":"dracula"}}
  // .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"
        }
      }
    }
  }
  ```

  ```json Claude Code theme={"theme":{"light":"dracula","dark":"dracula"}}
  // .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"
        }
      }
    }
  }
  ```

  ```json VS Code (Copilot) theme={"theme":{"light":"dracula","dark":"dracula"}}
  // .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"
        }
      }
    }
  }
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## 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

<Note>
  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.
</Note>

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

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    PRIVATE_KEY=0x... ARB_RPC_URL=https://... \
      node apps/mcp-server/dist/index.js
    ```

    The server should start without output (it communicates via stdio).
  </Accordion>

  <Accordion title="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)
  </Accordion>
</AccordionGroup>