ATV — DeFi Yield Vault MCP Server

AI-native access to Aarna's tokenized yield vaults on Ethereum and Base. 19 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_balance`	Underlying token breakdown
`get_historical_nav`	NAV data points over N days
`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/balance`	Token breakdown
GET	`/v1/vaults/:address/historical-nav`	Historical NAV

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

atv

Quick Install