ByteTree MCP

Copy page

When to use which surface
What’s inside
Transport encoding
Response-size discipline
Proprietary concepts
Conventions
Rate limits
Next steps

ByteTree MCP is an LLM-native, read-only interface to the same data plane that powers the REST API. It exposes tools that AI agents can call to retrieve assets, prices, metrics, group rollups, and FX data — and ships a glossary resource so the agent can ground its answers in ByteTree’s vocabulary without external lookup.

When to use which surface

Use case	Surface
Programmatic ingest, dashboards, scheduled jobs	REST API
Claude, ChatGPT, Claude Code, or another MCP client	ByteTree MCP
Custom agent workflows with tool-calling	ByteTree MCP
One-off curl, browser inspection, debugging	REST API

Both surfaces read the same engine. Choose the MCP when you want the LLM to drive the request loop and need glossary-aware semantics in-band; choose REST when you control the request shape directly.

Some data is REST-only today: the ByteTrend Monitor, Portfolios and the Dimensions listings have no MCP tool.

What’s inside

13 read-only data tools — asset discovery, price and FX data, latest and time-series metrics, server-side ranking, distributions, regime-transition events, group rollups, dataset summary, and asset comparison. See the Tool Reference. ByteTree MCP exposes 14 tools in total: these thirteen return data, and the fourteenth, ping, is a health check that confirms the connection is alive.
bytetree://glossary resource — authoritative definitions for CAPR, ByteTrend, trend regimes, trendAge200w, score-history fields, and universes. Pulled in-band by MCP clients; the human-readable form lives on the Concepts page.
Connect with your account or a key — sign in with your ByteTree account (no key) or send a per-customer API key as Authorization: Bearer <your-api-key>. Either way access resolves to your account and is checked on every request. See Authentication.

Transport encoding

ByteTree MCP responses use TOON — a compact, token-efficient encoding (lossless JSON in a denser YAML-flavoured form, with CSV-style tabular arrays for uniform-row data). Most clients decode this transparently; you only see the difference if you’re inspecting raw transport or budgeting tokens directly. Read tabular blocks (header line ending in {field1,field2,…}: followed by comma-delimited rows) as arrays of objects with the listed fields in order.

Response-size discipline

The tool layer caps results at ~800 KB. Past the cap, the tool returns an explicit error with narrowing guidance rather than silently truncating — so an agent that retries with a smaller window or a fields projection succeeds on the next call.

Three tools — get_metrics_series, get_prices and get_regime_transitions — default to a 90-day window ending today when neither from nor to is supplied. The narrowing is silent: a date-less request for “all history” returns 90 days and no error says the range was reduced, so pass from explicitly whenever the question is historical. Widen explicitly when you need history, and use the fields input to project just the metrics you care about (the full metrics blob is ~100 fields × N days; without a projection a multi-year request will hit the cap).

The server publishes these conventions via the MCP instructions field returned during initialization — clients that surface that field will see the same default-window and narrowing-guidance framing alongside the TOON format notes, so a connected agent generally adapts without needing to read this page.

Proprietary concepts

Terms like CAPR (Currency-Adjusted Price Relative), ByteTrend (0–5 composite score in two arcs — Weekly with 200-week / 30-week MAs, Daily with 200-day / 30-day MAs; the wire-format suffixes …200w and …30d map to Weekly and Daily respectively), Local-vs-CAPR variants, and trend regimes (Leading / Emerging / Weakening / Bear / Neutral) are not in any LLM training set. Read the Concepts page or the in-band bytetree://glossary resource before reasoning about these fields. If your client doesn’t expose resources/read, call summarise_dataset first — its response carries an inline concepts block with one-line definitions.

Conventions

Asset symbols are uppercased internally (case-insensitive on input).
Dates are ISO YYYY-MM-DD strings.
The bulk ranking surface (rank_assets) only includes assets with a metrics row from the last 7 days, while the per-symbol tools (get_latest_metrics, compare_assets) return the newest row whatever its age — check its date before treating the values as current.

Rate limits

Requests are rate-limited per account, with a separate limit on repeated invalid credentials (such as a wrong API key) from one network address. A request over the limit gets 429 Too Many Requests with a Retry-After header (seconds to wait) and RateLimit-* headers describing the window. Wait the Retry-After seconds before retrying — retrying sooner is refused again. Everyday use by one assistant stays well within the limit; if you run many agents on one account and hit it routinely, contact ByteTree.

Next steps

Getting Started — endpoints, auth, and client configs.
Tool Reference — the 13 data tools, their inputs, and response shapes.
Concepts — CAPR, ByteTrend, trend regimes, universes, trendAge200w.