# A Crypto Portfolio MCP Server for AI Agents

> How to give Claude, Codex or Gemini live on-chain portfolio data through an MCP server, and why token-only APIs make agents confidently wrong about wallets.

- **URL:** https://octav.fi/blog/crypto-portfolio-mcp-server
- **Published:** 2026-05-28
- **Author:** Octav Team — Portfolio Intelligence for Digital Assets
- **Topic:** AI Agents
- **Tags:** mcp, ai-agents, api
- **Source:** Octav, Practical guides on crypto NAV reporting, multi-chain portfolio management and digital asset APIs, from the team behind Octav.

---
An AI agent asked to analyse a wallet is only as good as the data it can reach.
Give it a token-only API and it will produce a fluent, well-structured, badly
wrong answer — because it has no way to know that the lending, staking and perp
positions were never in the response.

The [Model Context Protocol](https://modelcontextprotocol.io) is how you hand an
agent a real data source. Octav ships an MCP server for exactly this.

## What the MCP server exposes

Once connected, the agent can call the Octav API directly as tools — portfolio,
transactions, NAV, historical snapshots and the rest of the
[endpoint surface](/crypto-portfolio-api-endpoint-reference) — without you
writing any glue code.

| Capability | What the agent can do |
| --- | --- |
| Portfolio | Resolve an address into decoded positions across chains |
| Transactions | Pull labelled transaction history with filters |
| NAV | Fetch a single net asset value figure |
| Historical | Ask what a portfolio looked like on a past date |
| Chains / protocols | Discover what is supported before querying |

## Setup

The server is at
[github.com/Octav-Labs/octav-api-mcp](https://github.com/Octav-Labs/octav-api-mcp).
Add it to your MCP client configuration:

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

Then ask in natural language:

```
What DeFi positions does 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 hold,
and what is the total exposure by chain?
```

The agent calls the portfolio tool, receives decoded positions, and reasons
over real data instead of guessing.

## Why decoding matters more for agents than for humans

A human looking at a dashboard notices when a position is missing — they know
they have a Kamino loan and can see it is absent. An agent has no prior. It
treats the API response as the complete state of the world.

That makes silent omission uniquely dangerous in agent workflows. An API that
returns 200 OK with half a portfolio does not produce a visible error; it
produces a confident conclusion built on missing data. The mechanics of that
failure are covered in
[Why Portfolio APIs Disagree About Net Worth](/why-portfolio-apis-disagree).

## The rest of the agent toolkit

The MCP server is one of four ways to give an agent portfolio access:

| Tool | Use it when |
| --- | --- |
| MCP server | The agent runs in Claude, Codex, Gemini or another MCP client |
| [Agent skill](https://github.com/Octav-Labs/octav-api-skill) | You want the agent to learn the API's shape and conventions |
| [Rust CLI](/octav-cli-rust) | The agent has shell access and you want terminal-native calls |
| [x402 pay-per-call](/x402-pay-per-call-api) | The agent should pay per request without a provisioned key |

## A note on rate limits and cost

Agents are enthusiastic. They will happily call an endpoint in a loop.

The API allows 360 requests per minute per key and bills in credits at roughly
$0.020–$0.025 each, with most endpoints costing one credit. Two practical
defences: pass multiple addresses in a single request rather than looping
(`?addresses=0x123,0x456`), and rely on the built-in caching — portfolio
responses cache for one minute, transactions for ten.

If you want hard spend limits per call rather than a shared key, that is what
[x402 is for](/octav-cli-rust).