Airohead MCP · Robinhood Chain

Airohead MCP

A Model Context Protocol server that gives Claude — or any MCP-capable agent — the Airohead engine as native tools: live market data and regime reads for every tracked instrument on Robinhood Chain, hunts with a paper trade leg, alerts, the AIRO analyst, and the Airo Engine’s deep intelligence. Hosted, one URL, authenticated with an API key that acts as your account and nothing more.

20 tools·server v1.6.0·chain 4663·protocol 2025-06-18

claude code · one command

claude mcp add airohead --transport http https://airofinance.io/api/mcp \
  --header "Authorization: Bearer AIRO_API_KEY"

Replace AIRO_API_KEY with a key from Settings → API keys. Other clients: see Install.

Install Browse the 20 tools

What your agent gets

Five surfaces, one connection.

Each card names the exact tools behind it. Nothing here is a plan — every tool listed is registered on the server today and appears in tools/list.

Reads the market and its regime

Every instrument Airohead tracks — price, 24h change, high/low, volume, volatility, perp funding and the 0–100 edge score — plus the deterministic regime label and the precision board that says how tradeable each one really is.

list_marketsmarket_regimemarket_precision

Builds and arms hunts

Multi-condition hunts with an optional trade leg — direction, take-profit, stop-loss — that the engine evaluates on paper every 30 seconds. Replay a draft's triggers over recorded history before arming it.

create_huntlist_huntsbacktest_huntpause_huntdelete_hunt

Reads results back honestly

Alerts with the briefing behind each trigger, the measured track record of strategy hunts from real closed paper positions, and the portfolio's numbers — zeros are honest zeros.

list_alertshunt_performanceget_portfolio

Asks the AIRO analyst

One grounded analyst call. It answers only from the tracker data in list_markets and will not invent a metric it cannot read. Analysis, never financial advice.

ask_airo

Deep intelligence

Grounded market context, a structure read with the multi-timeframe gate, full pre-trade analysis, Monte Carlo odds, Robinhood Chain token forensics and the engine's research reports — every figure backed by a live feed, every gap named.

engine_market_contextengine_structureengine_pretradeengine_tokenengine_reportsengine_montecarloengine_reports_generate

Install

Point your client at the endpoint.

Airohead MCP is hosted at https://airofinance.io/api/mcp. It speaks MCP’s JSON-RPC 2.0 over HTTP POST, so any client that connects to a remote server by URL works — nothing to clone, no runtime to keep alive. Replace AIRO_API_KEY with your key.

Claude Code — CLI

terminal

claude mcp add airohead --transport http https://airofinance.io/api/mcp \
  --header "Authorization: Bearer AIRO_API_KEY"

Claude Code — .mcp.json

json

{
  "mcpServers": {
    "airohead": {
      "type": "http",
      "url": "https://airofinance.io/api/mcp",
      "headers": { "Authorization": "Bearer AIRO_API_KEY" }
    }
  }
}

Claude Desktop

json · remote MCP server

{
  "mcpServers": {
    "airohead": {
      "type": "http",
      "url": "https://airofinance.io/api/mcp",
      "headers": { "Authorization": "Bearer AIRO_API_KEY" }
    }
  }
}

Cursor — mcp.json

json

{
  "mcpServers": {
    "airohead": {
      "url": "https://airofinance.io/api/mcp",
      "headers": { "Authorization": "Bearer AIRO_API_KEY" }
    }
  }
}

The key is accepted as Authorization: Bearer airo_sk_… or as an X-Airohead-Key header. Cross-origin requests are allowed, so browser-based connectors can reach the endpoint directly. The endpoint has no server-push stream: a GET returns 405, and every exchange is a plain POST.

Prefer a local process? (stdio)

For clients that spawn a command instead of connecting by URL, the repo ships a dependency-free stdio launcher — bun run mcp from a checkout. It serves the identical tool list from the same registry and forwards every call to the hosted API, so it needs the same key plus the host to talk to. AIROHEAD_URL defaults to a local dev server; set it to the hosted origin.

terminal · from the repo root

AIROHEAD_API_KEY=AIRO_API_KEY AIROHEAD_URL=https://airofinance.io bun run mcp

Or let the client spawn it:

json · stdio

{
  "mcpServers": {
    "airohead": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/airohead/mcp/airohead-mcp.ts"],
      "env": {
        "AIROHEAD_API_KEY": "AIRO_API_KEY",
        "AIROHEAD_URL": "https://airofinance.io"
      }
    }
  }
}

Run it in a terminal by hand and it prints a banner, the tool roster and a small console instead of raw JSON-RPC — type whoami or list_markets to try a tool.

Verify

Make a first call.

The manifest is public: initialize and tools/list need no key. Calling a tool does. Ask your agent for whoami — it should name your account — or hit the endpoint directly.

List the tools (no key)

curl

curl -s https://airofinance.io/api/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call list_markets (key required)

curl

curl -s https://airofinance.io/api/mcp \
  -H "content-type: application/json" \
  -H "Authorization: Bearer AIRO_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_markets","arguments":{}}}'

A tool result arrives as MCP content: one text block holding the JSON. For list_markets that is an array — one row per tracked instrument with the fields the tool description names, plus live (false while a row is still seed data) and updatedAt. Exact keys: check the endpoint.

response shape

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "[ { \"symbol\": \"…/USDG\", \"price\": …, \"live\": true, … } ]" }],
    "isError": false
  }
}

What a missing key looks like

The call is not rejected at the HTTP layer — it comes back as a tool result with isError: true so the agent can read it:

tool result · text

Airohead error: no valid API key. Send it as `Authorization: Bearer airo_sk_...`.
Create one in Airohead → Settings → API keys.

Get a key

Keys come from the dashboard.

A key is a headless credential for one account. It inherits exactly that account's permissions and cannot widen them.

1. Open the dashboard and sign in with a wallet signature.
2. Go to Settings → API keys.
3. Type a label (for example Claude Desktop) and press Create.
4. Copy the key. It is shown once; the panel also offers a ready-made claude mcp add command with the key filled in.

Format: airo_sk_… — sent as a Bearer token
Shown: Once. Only a hash is stored; a lost key is replaced, not recovered.
Limit: 10 active keys per account — revoke one to create another.
Revoke: Same panel. The next request with that key fails immediately.
Scope: Acts as your account. Cannot create or revoke keys — that needs a signed-in session.

Architecture

One registry, two transports.

The HTTP endpoint and the stdio launcher read the same tool list, so a tool can never exist on one and not the other. Every call runs a real engine procedure as the account behind the key.

diagram

  Claude · Cursor · any MCP client
        │  JSON-RPC 2.0 over HTTP POST  (Authorization: Bearer airo_sk_…)
        ▼
  https://airofinance.io/api/mcp
        │  one tool registry, shared with the stdio launcher
        ▼
  ┌──────────────────────────────────────────────┐
  │  Airohead engine — 30-second tick             │
  │  market data · regime · hunts · alerts · AIRO │
  └──────────────────────────────────────────────┘
        │  engine_* tools
        ▼
  ┌──────────────────────────────────────────────────────────────────┐
  │  Airo Engine — deep intelligence                                  │
  │  context · structure · pre-trade · Monte Carlo · token · reports │
  └──────────────────────────────────────────────────────────────────┘

Endpoint: https://airofinance.io/api/mcp
Transport: JSON-RPC 2.0 over HTTP POST. Batches (a JSON array) are accepted.
Methods: initialize · ping · tools/list · tools/call · notifications/initialized
Auth: Authorization: Bearer airo_sk_… or X-Airohead-Key: airo_sk_…
CORS: Any origin; authorization and MCP session headers allowed.
Output privacy: Tool results are shaped before they leave: upstream feed names, internal ids and raw server errors never reach the agent. Request-shaped errors (bad input, not found) are forwarded so the agent can act on them.

Tools reference

20 tools, exactly as the server lists them.

Names, descriptions and inputs mirror the server’s tool registry — the same list tools/list serves, which is always the authoritative answer. * marks a required input. Prices and position sizes are integer cents and percentages are ×100 in the hunt tools; the engine tools take plain USD and plain percents — each schema says which.

Market + regime

Every tracked instrument, its regime classification and its precision board.

3 tools

Tool	What it does	Inputs
`list_markets` read	Live market data for every instrument Airohead tracks: price, 24h change, 24h high/low, volume, volatility, perp funding, and Airohead's 0-100 edge score. Refreshed on a 30-second cycle. Start here — other tools need these exact symbols.	none
`market_regime` read	The deterministic regime classification for every tracked instrument: trending / mean_reverting / high_vol / illiquid, with a direction, a 0-100 confidence and a 0-100 precision score. Computed by arithmetic over recorded price history — no model, no guessing. `regime` can be null: that is the engine refusing to label thin or stale history, and `reason` says which.	none
`market_precision` read	Precision (executability) for every tracked instrument, ranked most-tradeable first. Not edge: edge rises with volatility, precision falls with it — high edge with low precision is the trap. Each result carries `maxAttainable`, `trust` and `missingInputs`.	none

Hunts / strategies

Saved conditions the engine re-checks every 30 seconds, with an optional paper trade leg.

6 tools

Tool	What it does	Inputs
`list_hunts` read	The user's Hunts grouped by status (armed / triggered / history). A Hunt is a saved set of market conditions the engine re-checks every 30 seconds; each carries a plain-language narration of exactly what it evaluates.	none
`create_hunt` write	Create a Hunt. With side='none' it only alerts. With side='long'\|'short' it becomes a strategy: on trigger the engine opens a tracked paper position and closes it on take-profit / stop-loss. Paper only — no real funds move and no exchange order is placed. Only tracked symbols are valid; call list_markets first.	name* · string rules* · array of object (1–6) logic · all \| any cooldownMinutes · number side · none \| long \| short tradeSymbol · string positionSizeUsd · number · cents takeProfitPct · number · ×100 stopLossPct · number · ×100
`pause_hunt` write	Pause an armed Hunt so the engine stops evaluating it.	huntId* · number
`delete_hunt` write	Delete a Hunt permanently. Irreversible — confirm with the user before calling.	huntId* · number
`backtest_hunt` write	Replay a draft Hunt's conditions against collected market history to see how often it would have fired, before arming it. Uses only history Airohead has actually recorded.	rules* · array of object (1–6) logic · all \| any cooldownMinutes · number days · number · 1–90
`hunt_performance` read	Measured track record for the user's strategy Hunts, computed from real closed paper positions: win rate, realized P&L, and open positions marked to the live price. Never user-typed.	none

Alerts + portfolio

What fired, the briefing behind it, and the account's measured numbers.

2 tools

Tool	What it does	Inputs
`list_alerts` read	Alerts the user has received. Each carries AIRO's briefing for the trigger: thesis, evidence, risk, and the invalidation level.	none
`get_portfolio` read	The user's portfolio: equity, realized/unrealized P&L, Sharpe, hit rate, drawdown and asset exposure. Values are manual entries plus strategy-Hunt results — zeros are honest zeros, not errors.	none

AIRO analyst

The one tool that runs a model. Grounded on tracker data only.

1 tool

Tool	What it does	Inputs
`ask_airo` write	Ask AIRO, Airohead's market analyst, a question. It answers only from Airohead's live tracker data (the instruments in list_markets) — it has no other data source and will not invent metrics. Analysis only, never financial advice.	message* · string · ≤2000 conversationId · number

Airo Engine

Deep intelligence: market context, structure, pre-trade analysis, Monte Carlo, token forensics and research reports.

7 tools

Tool	What it does	Inputs
`engine_market_context` read	Grounded market context for one asset from the Airo Engine: a plain-text brief covering spot, 24h range, derivatives (funding, open interest, liquidations), whale flows, macro and news — built only from feeds that actually answered. `available: false` means no feed answered.	symbol* · string · bare ticker
`engine_structure` read	Market structure read for one asset and timeframe: trend, structure score, swings, break-of-structure and change-of-character events, trendlines, graded support/resistance, auto S/R, and the multi-timeframe gate (`mtf`). Pure arithmetic over real candles. Each pass is null with a named reason when it could not run.	symbol* · string · bare ticker timeframe · 1m \| 5m \| 15m \| 30m \| 1h \| 4h \| 1d \| 1w direction · long \| short
`engine_pretrade` read	Full pre-trade analysis for a proposed position: volatility (ATR, RSI, daily vol), candidate stops and targets with reasons, invalidation, position size for the stated risk, risk/reward, a Monte Carlo of stop-vs-target odds, Kelly sizing, a scored checklist and one verdict. Money inputs are plain USD and percents are plain (1 = 1%). Analysis only, never financial advice. Requires a signed-in user.	symbol* · string · bare ticker timeframe · 1m \| 5m \| 15m \| 30m \| 1h \| 4h \| 1d \| 1w side · long \| short entry · number · USD capital · number · USD riskPct · number · % maxStopPct · number · % atrMult · number horizonDays · number
`engine_token` read	Forensics for any token on Robinhood Chain by contract address: symbol, name, decimals, total supply, holder count, top-holder and top-10 concentration, and the supply split — `liquidityPct`, `lockedPct`, `burnedPct`. A null figure means the engine could not measure it, not zero. `ok: false` with kind 'not_found' means the address is not a token on this chain.	address* · string · 0x address
`engine_reports` read	Index of the engine's research reports, newest first: id, type, title, symbol, generated_at, bias, confidence, rating, conviction, a one-paragraph summary, tags, and whether the report is attested on-chain and graded against the realized move. Summaries only. Optionally filter by symbol.	limit · number · 1–100 symbol · string · bare ticker
`engine_montecarlo` read	Monte Carlo path simulation for one proposed trade: the probability the stop is hit before any target, the probability of ending in profit, per-target hit odds, expected and median R, the p05/p50/p95 terminal prices and average excursion. Volatility is derived from real candles unless `dailyVolPct` is supplied. Deterministic for a given `seed`. Money inputs are plain USD, percents are plain (2.5 = 2.5%). Analysis only, never financial advice.	symbol* · string · bare ticker entry* · number · USD timeframe · 1m \| 5m \| 15m \| 30m \| 1h \| 4h \| 1d \| 1w stop · number · USD targets · array of number · USD (≤10) direction · long \| short dailyVolPct · number · % horizonDays · number paths · number · 100–20000
`engine_reports_generate` write	Write a new research report for one asset and return it in full: bias, confidence, rating, conviction, thesis, key drivers, risks, scenarios, trade structures and the market snapshot it was written from. `format: 'standard'` is one model pass; `'institutional'` runs a five-pass adversarial chain (slow — minutes). Limited to 3 per hour per user. Resolves to `{ available: true, report }` or `{ available: false, reason }` — never fabricates a report. AI-generated research, not financial advice. Requires a signed-in user.	symbol* · string · bare ticker type · market_structure \| whale_intelligence \| options_flow \| cycle_position \| funding_arbitrage \| liquidation_cascade \| institutional_research format · standard \| institutional focus · string · ≤600

Account

Confirm which account the key acts as.

1 tool

Tool	What it does	Inputs
`whoami` read	The Airohead account this API key is acting as. Use it to confirm the key works.	none

Rate limits

Per IP at the door, per account inside.

Two limiters sit on the endpoint itself; a few tools carry their own burst limit on the procedure they call. There is no guest tier — every tools/call needs a key.

Endpoint

120 requests / min

Per IP, any method. Checked before the body is parsed.

tools/call

60 calls / min

Per IP. A batch spends one slot per call it carries and is refused whole if it would cross the line.

Over the limit

HTTP 429

JSON-RPC error code -32029 (RATE_LIMITED) with a retry-after header in seconds.

ask_airo: 6 calls / min per account — the one tool that runs a model.
engine_pretrade: 12 calls / min per account — a full engine run costs real compute.
engine_reports_generate: 3 calls / hour per account — one model pass (standard) or five (institutional).
Other tools: No additional per-tool limit beyond the endpoint limits above. Engine reads are cached server-side, so repeated calls inside a window collapse to one request.

FAQ

Four straight answers.

Is it free?

Yes — free during the tech update. No tool on this endpoint is billed today. When metering lands it lands on the calls that run a model, and nowhere else.

Does it trade?

No. There is no order-placement tool and no custody of funds. A hunt with a trade leg opens paper positions that the engine marks to the live price for a measured record; nothing is sent to an exchange and your wallet is never touched. Live trading on the chain is built but blocked until a swap router is verified.

What chain?

Robinhood Chain, chainId 4663. Tracked instruments are quoted as SYMBOL/USDG; the engine tools take bare tickers (BTC, ETH, SOL) and normalise an Airohead symbol for you.

Can I use it without the dashboard?

Listing the tools needs no key, but calling one does — and a key can only be created from a signed-in dashboard session (Settings → API keys). A key cannot mint another key, so the dashboard is the one place that step happens.

Create a key, paste one line, ask your agent what is moving.

Free during the tech update. No tiers, no agent surcharge, no order placement.

Get a key