MCP Server - Octav Developer Docs

Features
Installation
Configuration
Claude Desktop
Cursor
VS Code (Copilot)
Claude Code
Available Tools
Portfolio & Holdings
Transactions
Historical & Snapshots
Metadata
Specialized
Example Prompts
Error Handling
Resources

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.

Quick Install — Run the MCP server with no installation required:

npx octav-api-mcp

Features

Portfolio & Holdings

Multi-chain portfolio aggregation

Wallet balances and DeFi positions
Net worth in multiple currencies
Token distribution overview

Transaction History

Complete transaction records

Filter by chain, type, and date range
Manual sync triggers
Up to 250 results per query

Historical Snapshots

Time-series portfolio data

Point-in-time snapshots
Automatic daily subscriptions
Performance tracking

Specialized Data

Additional capabilities

Solana airdrop eligibility
Polymarket positions
x402 agent payment support

Installation

npx (Recommended)
npm
pnpm

No installation required — run directly:

npx octav-api-mcp

Install globally:

npm install -g octav-api-mcp

Then run:

octav-api-mcp

Install globally:

pnpm add -g octav-api-mcp

Then run:

octav-api-mcp

Configuration

You’ll need an Octav API key. Get one at data.octav.fi.

Claude Desktop

macOS
Windows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Cursor

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

{
  "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:

{
  "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:

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

octav_get_portfolio

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

octav_get_wallet

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

octav_get_nav

Total net worth in a specified currency.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.
`currency`	string	No	`USD`, `EUR`, `GBP`, `JPY`, or `CNY`. Defaults to `USD`.

Cost: 1 credit per address

"What's the total net worth of 0x123... in EUR?"

octav_get_token_overview

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"

Transactions

octav_get_transactions

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

octav_sync_transactions

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

Historical & Snapshots

octav_get_historical

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

octav_subscribe_snapshot

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"

Metadata

octav_get_status

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

octav_get_credits

Check API credit balance and usage.No parameters required.Cost: Free

"How many API credits do I have left?"

Specialized

octav_get_airdrop

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"

octav_get_polymarket

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

octav_agent_wallet

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

octav_agent_portfolio

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

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
Rate limit exceeded	Too many requests per minute	Wait and retry — the server includes retry guidance

Resources

GitHub

Source code and issues

API Docs

Full REST API reference

Pricing

Credit packages and costs

AI Agents & LLMs

Building AI Agents