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

# MCP Server

> Connect AI assistants like Claude Desktop, Cursor, and VS Code to the Octav API through the Model Context Protocol

The official Octav MCP server lets AI assistants query portfolio data, transaction history, net worth, and historical snapshots across 20+ blockchains — directly from your conversation.

<Info>
  **Quick Install** — Run the MCP server with no installation required:

  ```bash theme={null}
  npx octav-api-mcp
  ```
</Info>

***

## Features

<CardGroup cols={2}>
  <Card title="Portfolio & Holdings" icon="wallet">
    Multi-chain portfolio aggregation

    * Wallet balances and DeFi positions
    * Net worth in multiple currencies
    * Token distribution overview
  </Card>

  <Card title="Transaction History" icon="receipt">
    Complete transaction records

    * Filter by chain, type, and date range
    * Manual sync triggers
    * Up to 250 results per query
  </Card>

  <Card title="Historical Snapshots" icon="clock">
    Time-series portfolio data

    * Point-in-time snapshots
    * Automatic daily subscriptions
    * Performance tracking
  </Card>

  <Card title="Specialized Data" icon="star">
    Additional capabilities

    * Solana airdrop eligibility
    * Polymarket positions
    * x402 agent payment support
  </Card>
</CardGroup>

***

## Installation

<Tabs>
  <Tab title="npx (Recommended)" icon="bolt">
    No installation required — run directly:

    ```bash theme={null}
    npx octav-api-mcp
    ```
  </Tab>

  <Tab title="npm" icon="npm">
    Install globally:

    ```bash theme={null}
    npm install -g octav-api-mcp
    ```

    Then run:

    ```bash theme={null}
    octav-api-mcp
    ```
  </Tab>

  <Tab title="pnpm" icon="box">
    Install globally:

    ```bash theme={null}
    pnpm add -g octav-api-mcp
    ```

    Then run:

    ```bash theme={null}
    octav-api-mcp
    ```
  </Tab>
</Tabs>

***

## Configuration

You'll need an Octav API key. Get one at [data.octav.fi](https://data.octav.fi/).

### Claude Desktop

<Tabs>
  <Tab title="macOS" icon="apple">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "octav": {
          "command": "npx",
          "args": ["-y", "octav-api-mcp"],
          "env": {
            "OCTAV_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows" icon="windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "octav": {
          "command": "npx",
          "args": ["-y", "octav-api-mcp"],
          "env": {
            "OCTAV_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Cursor

Go to **Cursor Settings > MCP** and add a new global MCP server:

```json theme={null}
{
  "mcpServers": {
    "octav": {
      "command": "npx",
      "args": ["-y", "octav-api-mcp"],
      "env": {
        "OCTAV_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to your VS Code `settings.json`:

```json theme={null}
{
  "mcp": {
    "servers": {
      "octav": {
        "command": "npx",
        "args": ["-y", "octav-api-mcp"],
        "env": {
          "OCTAV_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}
```

### Claude Code

Add the MCP server to your project with the Claude Code CLI:

```bash theme={null}
claude mcp add octav -- npx -y octav-api-mcp
```

Then set the API key as an environment variable or pass it via your shell profile.

***

## Available Tools

The MCP server exposes 14 tools organized by category. Most tools cost **1 credit per address**.

### Portfolio & Holdings

<AccordionGroup>
  <Accordion title="octav_get_portfolio" icon="wallet">
    **Complete portfolio including wallet holdings and DeFi positions across 20+ blockchains.**

    | Parameter   | Type      | Required | Description                                              |
    | ----------- | --------- | -------- | -------------------------------------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses (EVM `0x...` or Solana base58). Max 10. |

    **Cost:** 1 credit per address

    ```
    "Show me the full portfolio for 0x123..."
    ```
  </Accordion>

  <Accordion title="octav_get_wallet" icon="coins">
    **Wallet token balances only (excludes DeFi protocol positions).**

    | Parameter   | Type      | Required | Description               |
    | ----------- | --------- | -------- | ------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10. |

    **Cost:** 1 credit per address

    ```
    "What tokens does 0x123... hold?"
    ```
  </Accordion>

  <Accordion title="octav_get_nav" icon="calculator">
    **Total net worth in a specified currency.**

    | Parameter   | Type      | Required | Description                                                                                                      |
    | ----------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10.                                                                                        |
    | `currency`  | string    | No       | Fiat: `USD`, `EUR`, `CAD`, `AED`, `CHF`, `SGD`. Crypto: `ETH`, `SOL`, `cbBTC`, `EURC`, `BNB`. Defaults to `USD`. |

    **Cost:** 1 credit per address

    ```
    "What's the total net worth of 0x123... in EUR?"
    ```
  </Accordion>

  <Accordion title="octav_get_token_overview" icon="chart-pie">
    **Aggregated token distribution across all chains.**

    | Parameter   | Type      | Required | Description                           |
    | ----------- | --------- | -------- | ------------------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10.             |
    | `date`      | string    | Yes      | Snapshot date in `YYYY-MM-DD` format. |

    **Cost:** 1 credit per address

    ```
    "Show me the token breakdown for 0x123... as of 2025-01-15"
    ```
  </Accordion>
</AccordionGroup>

### Transactions

<AccordionGroup>
  <Accordion title="octav_get_transactions" icon="receipt">
    **Query transaction history with filtering and pagination.**

    | Parameter   | Type      | Required | Description                                         |
    | ----------- | --------- | -------- | --------------------------------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10.                           |
    | `chain`     | string    | No       | Filter by chain (e.g., `ethereum`, `solana`).       |
    | `type`      | string    | No       | Filter by type (e.g., `transfer`, `swap`, `stake`). |
    | `startDate` | string    | No       | Start date (`YYYY-MM-DD`).                          |
    | `endDate`   | string    | No       | End date (`YYYY-MM-DD`).                            |
    | `limit`     | number    | No       | Results per request (1–250, default 50).            |
    | `offset`    | number    | No       | Pagination offset (default 0).                      |

    **Cost:** 1 credit per address

    ```
    "Show me the last 20 swaps on Ethereum for 0x123..."
    ```
  </Accordion>

  <Accordion title="octav_sync_transactions" icon="arrows-rotate">
    **Trigger manual transaction synchronization for immediate indexing.**

    | Parameter   | Type      | Required | Description               |
    | ----------- | --------- | -------- | ------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10. |

    **Cost:** 1 credit per address

    ```
    "Sync the latest transactions for 0x123..."
    ```
  </Accordion>
</AccordionGroup>

### Historical & Snapshots

<AccordionGroup>
  <Accordion title="octav_get_historical" icon="clock">
    **Portfolio snapshot for a specific past date.**

    | Parameter   | Type      | Required | Description                  |
    | ----------- | --------- | -------- | ---------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10.    |
    | `date`      | string    | Yes      | Date in `YYYY-MM-DD` format. |

    **Cost:** 1 credit per address

    ```
    "What was my portfolio worth on 2024-12-31?"
    ```
  </Accordion>

  <Accordion title="octav_subscribe_snapshot" icon="bell">
    **Subscribe to automatic daily portfolio snapshots.**

    | Parameter     | Type      | Required | Description                          |
    | ------------- | --------- | -------- | ------------------------------------ |
    | `addresses`   | string\[] | Yes      | Wallet addresses. Max 10.            |
    | `description` | string    | No       | Optional label for the subscription. |

    **Cost:** 1,200 credits

    ```
    "Subscribe 0x123... to daily snapshots"
    ```
  </Accordion>
</AccordionGroup>

### Metadata

<AccordionGroup>
  <Accordion title="octav_get_status" icon="circle-check">
    **Check sync status of addresses across all chains.**

    | Parameter   | Type      | Required | Description               |
    | ----------- | --------- | -------- | ------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10. |

    **Cost:** Free

    ```
    "Is 0x123... fully synced?"
    ```
  </Accordion>

  <Accordion title="octav_get_credits" icon="tag">
    **Check API credit balance and usage.**

    No parameters required.

    **Cost:** Free

    ```
    "How many API credits do I have left?"
    ```
  </Accordion>
</AccordionGroup>

### Specialized

<AccordionGroup>
  <Accordion title="octav_get_airdrop" icon="gift">
    **Check airdrop eligibility for a Solana address.**

    | Parameter | Type   | Required | Description                     |
    | --------- | ------ | -------- | ------------------------------- |
    | `address` | string | Yes      | Solana wallet address (base58). |

    **Cost:** 1 credit

    ```
    "Check airdrop eligibility for my Solana wallet"
    ```
  </Accordion>

  <Accordion title="octav_get_polymarket" icon="chart-line">
    **Get Polymarket prediction market positions.**

    | Parameter | Type   | Required | Description                        |
    | --------- | ------ | -------- | ---------------------------------- |
    | `address` | string | Yes      | Ethereum wallet address (`0x...`). |

    **Cost:** 1 credit

    ```
    "Show my Polymarket positions for 0x123..."
    ```
  </Accordion>

  <Accordion title="octav_agent_wallet" icon="robot">
    **Wallet holdings via x402 payment protocol for AI agents with automatic payment.**

    | Parameter   | Type      | Required | Description               |
    | ----------- | --------- | -------- | ------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10. |

    **Cost:** Paid via HTTP 402 payment protocol
  </Accordion>

  <Accordion title="octav_agent_portfolio" icon="robot">
    **Full portfolio via x402 payment protocol for AI agents with automatic payment.**

    | Parameter   | Type      | Required | Description               |
    | ----------- | --------- | -------- | ------------------------- |
    | `addresses` | string\[] | Yes      | Wallet addresses. Max 10. |

    **Cost:** Paid via HTTP 402 payment protocol
  </Accordion>
</AccordionGroup>

***

## Example Prompts

Once the MCP server is connected, you can ask your AI assistant questions like:

```
"What's the total value of my portfolio at 0xABC...?"
```

```
"Show me all swap transactions on Arbitrum for the past month"
```

```
"Compare my portfolio value today vs. 30 days ago"
```

```
"Check if my Solana wallet is eligible for any airdrops"
```

```
"How many API credits do I have left?"
```

***

## Error Handling

The MCP server returns clear error messages for common issues:

| Error                  | Cause                                      | Solution                                                 |
| ---------------------- | ------------------------------------------ | -------------------------------------------------------- |
| Invalid address format | Address doesn't match EVM or Solana format | Use `0x...` (40 hex chars) for EVM or base58 for Solana  |
| Authentication failure | Missing or invalid API key                 | Check your `OCTAV_API_KEY` environment variable          |
| Insufficient credits   | Not enough credits for the request         | Purchase more at [data.octav.fi](https://data.octav.fi/) |
| Rate limit exceeded    | Too many requests per minute               | Wait and retry — the server includes retry guidance      |

***

## Resources

<CardGroup cols={3}>
  <Card title="GitHub" icon="github" href="https://github.com/Octav-Labs/octav-api-mcp">
    Source code and issues
  </Card>

  <Card title="API Docs" icon="book" href="/api/introduction">
    Full REST API reference
  </Card>

  <Card title="Pricing" icon="tag" href="/api/pricing">
    Credit packages and costs
  </Card>
</CardGroup>