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

# MCP Server

> Model Context Protocol server for AI tool integration

## Overview

The ouroborai MCP server exposes Arbitrum DeFi tools through the [Model Context Protocol](https://modelcontextprotocol.io), 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:

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

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

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

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

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

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

## Configuration

### Claude Desktop

Add the server to your `claude_desktop_config.json`:

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

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

### Cursor

Add the server to your Cursor MCP settings (`.cursor/mcp.json` in your project root):

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

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

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

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

## Tool usage examples

Here are example interactions showing how Claude uses the MCP tools:

<AccordionGroup>
  <Accordion title="Swap tokens">
    **User:** Swap 100 USDC for ETH

    **Claude calls:** `arb_quote` with `{ tokenIn: "USDC", tokenOut: "WETH", amountIn: "100" }`

    **Tool returns:**

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

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    { "txHash": "0xabc...", "status": "submitted" }
    ```
  </Accordion>

  <Accordion title="Check lending health">
    **User:** What is my Aave health factor?

    **Claude calls:** `arb_lend_health` with `{}`

    **Tool returns:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "healthFactor": "2.4500",
      "status": "safe",
      "totalCollateralUsd": "5000.000000",
      "totalDebtUsd": "1000.000000",
      "availableBorrowsUsd": "2500.000000",
      "ltv": "50.0%"
    }
    ```
  </Accordion>

  <Accordion title="Open a perpetual position">
    **User:** Open a 10x long on ETH/USDC with 500 USDC collateral

    **Claude calls:** `arb_perp_open` with:

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "market": "ETH/USDC",
      "side": "long",
      "collateralUsdc": "500",
      "leverage": 10
    }
    ```

    **Tool returns:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "txHash": "0xdef...",
      "status": "order submitted to GMX keepers"
    }
    ```
  </Accordion>

  <Accordion title="Full portfolio view">
    **User:** Show me my portfolio

    **Claude calls:** `arb_portfolio` with `{}`

    **Tool returns:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "wallet": "0xYourAddress",
      "balances": {
        "eth": "1.250000",
        "usdc": "3200.000000"
      },
      "aave": {
        "healthFactor": "2.4500",
        "collateral": "5000.000000",
        "debt": "1000.000000"
      },
      "gmxPositions": 1,
      "timeboost": {
        "isController": false
      }
    }
    ```
  </Accordion>
</AccordionGroup>

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

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.