io.github.aarna-ai/atv

ATV — DeFi Yield Vault MCP Server

AI-native access to Aarna's tokenized yield vaults on Ethereum and Base. 20 tools for vault discovery, performance metrics, transaction building, and portfolio tracking.

API Base URL: https://atv-api.aarna.ai MCP Endpoint: https://atv-api.aarna.ai/mcp (Streamable HTTP) API Docs: https://atv-api.aarna.ai/docs

API Access

The hosted API at https://atv-api.aarna.ai is available to anyone with a valid API key. All requests require an x-api-key header.

To get an API key, reach out to us at dev@aarnalab.dev.

Quick Start (30 seconds)

Once you have your API key, add the config to your client:

Claude Desktop

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

{
  "mcpServers": {
    "atv": {
      "url": "https://atv-api.aarna.ai/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Claude Code

claude mcp add atv --transport http https://atv-api.aarna.ai/mcp --header "x-api-key: YOUR_API_KEY"

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "atv": {
      "url": "https://atv-api.aarna.ai/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

VS Code (Copilot)

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "atv": {
        "url": "https://atv-api.aarna.ai/mcp",
        "headers": { "x-api-key": "YOUR_API_KEY" }
      }
    }
  }
}

mcp-remote (fallback for stdio-only clients)

{
  "mcpServers": {
    "atv": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://atv-api.aarna.ai/mcp", "--header", "x-api-key:YOUR_API_KEY"]
    }
  }
}

Available Tools (19)

Discovery & Metadata

Tool	Description
list_vaults	List all vaults, optionally filter by chain
get_vault	Get metadata for a specific vault by address

Performance Metrics

Tool	Description
get_vault_nav	Current NAV (Net Asset Value) in USD
get_vault_tvl	Current TVL (Total Value Locked) in USD
get_vault_apy	APY breakdown: base + reward + total

Operational Status

Tool	Description
get_deposit_status	Whether deposits are paused
get_withdraw_status	Whether withdrawals are paused
get_queue_withdraw_status	Whether queued withdrawals are paused

Transaction Builders (Instant)

Tool	Description
build_deposit_tx	Build approve + deposit transaction steps
build_withdraw_tx	Build withdrawal transaction steps
build_stake_tx	Build approve + stake steps (timelock vaults)
build_unstake_tx	Build unstake step (timelock vaults)

Transaction Builders (Queued)

Tool	Description
build_queue_withdraw_tx	Initiate a queued withdrawal
build_unqueue_withdraw_tx	Cancel a pending queued withdrawal
build_redeem_withdraw_tx	Claim a completed queued withdrawal

Analytics

Tool	Description
get_vault_portfolio	Underlying token portfolio
get_historical_nav	NAV data points over a period (7, 30, 60, 360, max)
get_historical_tvl	TVL data points over a period (7, 30, 60, 360, max)
get_total_tvl	Platform-wide or per-vault TVL
get_user_investments	User portfolio and positions

Example Prompts

• "What DeFi vaults are available on Base?"
• "What's the current APY for vault 0x...?"
• "Build a deposit of 1000 USDC into vault 0x..."
• "Show my portfolio across all Aarna vaults"
• "Is the queue-withdraw paused on vault 0x...?"

REST API

All endpoints require x-api-key header and are prefixed with /v1.

Vault Endpoints

Method	Path	Description
GET	/v1/vaults	List all available vaults
GET	/v1/vaults/tvl	Platform-wide TVL
GET	/v1/vaults/:address	Vault metadata
GET	/v1/vaults/:address/nav	NAV price
GET	/v1/vaults/:address/tvl	Vault TVL
GET	/v1/vaults/:address/apy	APY breakdown
GET	/v1/vaults/:address/deposit-status	Deposit pause status
GET	/v1/vaults/:address/withdraw-status	Withdraw pause status
GET	/v1/vaults/:address/queue-withdraw-status	Queue-withdraw pause status
GET	/v1/vaults/:address/portfolio	Token portfolio
GET	/v1/vaults/:address/historical-nav	Historical NAV (days: 7,30,60,360,max)
GET	/v1/vaults/:address/historical-tvl	Historical TVL (days: 7,30,60,360,max)

Transaction Endpoints

Method	Path	Description
GET	/v1/deposit-tx	Build deposit calldata
GET	/v1/withdraw-tx	Build withdraw calldata
GET	/v1/stake-tx	Build stake calldata
GET	/v1/unstake-tx	Build unstake calldata
GET	/v1/queue-withdraw-tx	Build queue-withdraw calldata
GET	/v1/unqueue-withdraw-tx	Build unqueue-withdraw calldata
GET	/v1/redeem-withdraw-tx	Build redeem-withdraw calldata

Other Endpoints

Method	Path	Description
GET	/v1/user-investments	User portfolio data
ALL	/mcp	MCP server (Streamable HTTP)

Unauthenticated

Method	Path	Description
GET	/health	Health check
GET	/openapi.json	OpenAPI 3.1 spec
GET	/docs	Interactive API reference
GET	/llms.txt	LLM-friendly documentation (llms.txt spec)
GET	/.well-known/agent.json	A2A agent card

TypeScript SDK

import { AtvClient } from '@atv/sdk';

const client = new AtvClient({
  apiKey: 'atv_...',
  baseUrl: 'https://atv-api.aarna.ai',
});

const vaults = await client.vaults.list({ chain: 'base' });
const nav = await client.vaults.nav('0xVaultAddress');

Self-Hosting

docker build -t atv-api \
  --build-arg AWS_ACCESS_KEY_ID=... \
  --build-arg AWS_SECRET_ACCESS_KEY=... \
  --build-arg AWS_DEFAULT_REGION=us-east-1 .

docker run -p 3000:3000 atv-api

Required environment variables (set in AWS Secrets Manager under atv-sdk):

• DATABASE_URL — PostgreSQL connection string
• REDIS_URL — Redis host:port
• RPC_URL_ETHEREUM — Ethereum JSON-RPC endpoint
• RPC_URL_BASE — Base JSON-RPC endpoint
• STRAPI_URL — CMS URL
• STRAPI_API_TOKEN — CMS API token
• ENGINE_BASE_URL — Aarna engine API

Development

Prerequisites

• Node.js 20+
• pnpm
• PostgreSQL
• Redis

Setup

pnpm install
cp .env.example apps/api/.env
# Fill in environment variables
pnpm migrate
pnpm dev

API: http://localhost:3000 | Docs: http://localhost:3000/docs

Repository Structure

atv-sdk/
├── apps/api/              # Express API server + MCP server
├── packages/sdk/          # TypeScript SDK (@atv/sdk)
├── packages/mcp-server/   # npm connector package (@aarna-ai/mcp-server-atv)
├── server.json            # MCP registry manifest
└── docs/                  # Guides

Build

pnpm build
# API: apps/api/dist/
# SDK: packages/sdk/dist/ (CJS + ESM)

Customer Onboarding

See docs/customer-onboarding.md for how to generate API keys, manage tiers, revoke access, and run admin queries.

License

MIT — see LICENSE.