vfat Metrics MCP

A read-only Model Context Protocol server for querying public vfat Metrics position data by EVM address. It gives MCP clients structured access to current vfat/Sickle positions, NFT lifecycle actions, historical value and performance series, CSV exports, and a compact portfolio summary.

This is an independent community project. It is not affiliated with or endorsed by vfat, Sickle, or their contributors.

Tools

Tool	Purpose
get_vfat_positions	Return every current position and the provider's position fields
get_vfat_position	Find one position by NFT/token ID
get_vfat_portfolio_summary	Count positions by chain/protocol and aggregate selected USD metrics
get_vfat_position_actions	Group deposits, rebalances and other events by transaction
get_vfat_position_value_history	Return historical value, token balances and range state
get_vfat_position_performance	Return APR, ROI, PnL and balance time series
export_vfat_position_csv	Export actions, value history or performance as CSV text

Every tool is declared read-only and idempotent. The server cannot sign messages, submit transactions, rebalance liquidity, or move funds.

Requirements

• Node.js 20 or newer
• An MCP client such as Codex, Claude Desktop, or another MCP-compatible agent
• Internet access to https://info-api.vf.at

No API key is required.

Install and run

From a checkout:

npm install
npm run build
node dist/index.js

For development:

npm run dev

The default transport is stdio. The process writes protocol messages to stdout and diagnostics to stderr.

Codex configuration

Build the project, then add it to ~/.codex/config.toml:

[mcp_servers.vfat_metrics]
command = "node"
args = ["/absolute/path/to/vfat-metrics-mcp/dist/index.js"]

Restart Codex after changing MCP configuration. You can then ask, for example:

Show and summarize the current vfat positions for <EVM_ADMIN_ADDRESS>.

Analyze rebalance costs and cashflows for the position identified by <CHAIN_ID>, <SICKLE_ADDRESS>, <NFT_ID>, and <NFT_MANAGER_ADDRESS>.

Claude Desktop configuration

{
  "mcpServers": {
    "vfat-metrics": {
      "command": "node",
      "args": ["/absolute/path/to/vfat-metrics-mcp/dist/index.js"]
    }
  }
}

Streamable HTTP

For local development or a trusted private network:

npm run build
node dist/index.js --http

• MCP endpoint: http://127.0.0.1:3000/mcp
• Health endpoint: http://127.0.0.1:3000/health

HTTP mode is stateless. Do not expose it publicly without authentication, TLS, request limits, and a suitable reverse proxy. Configure it with MCP_HTTP_HOST, MCP_HTTP_PORT, or MCP_TRANSPORT=http.

Data and precision

The server reads public endpoints used by the vfat Metrics website:

GET https://info-api.vf.at/open-positions-v2?admin_address=<address>
GET https://info-api.vf.at/sickle-nft-actions?...position identity...
POST https://info-api.vf.at/historical-underlying-assets
GET https://info-api.vf.at/position-performance-history?...position identity...

The upstream endpoint is not documented as a stable public API and may change without notice. Raw position fields are passed through so new fields remain available. Portfolio totals use decimal.js; provider-supplied decimal strings are therefore summed without JavaScript binary floating-point addition.

USD values, PnL, ROI, APR, token prices, timestamps, range state, and rewards are provider-derived estimates. They may be delayed, incomplete, or calculated differently from on-chain state. Verify material decisions independently with on-chain reads and protocol contracts.

Position history

vfat can emit several raw rows for one transaction. get_vfat_position_actions groups them by transaction hash, selects the lifecycle action, sums provider cashflow fields with decimal arithmetic, and retains rewards and swaps. Set include_raw_events=true when an audit needs every provider row.

Value history follows NFT migrations and rebalances by discovering every token ID in the action chain before requesting historical underlying assets. Points at the same timestamp are aggregated into normalized token balances, USD values, and one in_range state.

All history tools accept optional inclusive from and to ISO 8601 timestamps. Position identity fields are supplied at runtime and are never stored by the server.

CSV export

export_vfat_position_csv accepts dataset=actions, value_history, or performance. It returns UTF-8 CSV text plus structured metadata (filename, mime_type, and row_count). The CSV is built from the same normalized JSON returned by the history tools, making calculations reproducible without browser automation.

Configuration

Copy .env.example values into your process environment if you need overrides:

Variable	Default	Meaning
VFAT_METRICS_API_URL	https://info-api.vf.at	Upstream base URL
VFAT_METRICS_TIMEOUT_MS	15000	Request timeout in milliseconds
MCP_TRANSPORT	stdio	stdio or http
MCP_HTTP_HOST	127.0.0.1	HTTP bind address
MCP_HTTP_PORT	3000	HTTP port

Development

npm run check

This runs formatting checks, ESLint, TypeScript typechecking, unit tests, and a production build.

License

MIT