@blackforge-so/mcp
A Model Context Protocol stdio server that puts
BlackForge market data in your agent's hands: real time crypto market data from the major
exchanges (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx), 150+ metrics for
14,000+ pairs, per pair per closed minute (1m on Ultra and PAYG; 5m, 1h and 1d rollups for every
plan).
Every column is a measurement with a definition: order book depth and shape, resting
liquidity lifetimes, trade-explained vs book-implied volume, spreads and market-wide context,
returned in context so an agent can read the raw microstructure directly. It is a thin client
over the public BlackForge /v1 API; it stores nothing and re-shapes nothing.
Quickstart
Add the server to your MCP client and paste an API key. Claude Desktop
(claude_desktop_config.json) or Claude Code (.mcp.json):
No install step: npx -y @blackforge-so/mcp fetches and runs the server on demand.
Where to get a key
Mint a key at app.blackforge.so → API. The server never
creates keys; it reads BLACKFORGE_API_KEY from its environment. The blackforge_catalog
tool works without a key, so you can verify the install before pasting one.
Tools
Plan entitlements (which venues, columns, and intervals a key may read) are enforced by the
API. When a column is dropped because your plan does not include it, the tool result reports
it in columnsOmitted so the agent understands why a key is absent. Venue- or interval-level
restrictions come back as a clear tool error carrying the HTTP status and the server's message
(including the upgrade URL, verbatim).
Live formulas and the live order book
Beyond the stored history, the server reaches BlackForge's realtime host. Write your own
measure from order book and trade data across the major venues, stream it every second, and
get notified when it crosses a value you choose.
A formula looks like mid(binance:BTCUSDT) - mid(okx:BTC-USDT) or
buyVol(binance:SOLUSDT, 60s) / max(sellVol(binance:SOLUSDT, 60s), 1). Pairs are spelled
exactly as blackforge_symbols lists them. The full function list is in the
blackforge_formula_validate tool description. Streaming and notifications are charged one
row per referenced pair per evaluation; live book reads by levels returned or walked, against
the same monthly quota as everything else. Every streamed value carries flags (for example
WARMING while a windowed term has not filled its window yet) and null means there was no
number, never zero.
The stream uses Node's built-in WebSocket, so blackforge_formula_watch needs Node 22 or
newer; every other tool runs on Node 20. Your key travels in the x-api-key header, never
in a URL.
Charts
blackforge_series also ships an interactive chart. A host that implements the
MCP Apps extension
(io.modelcontextprotocol/ui) renders the result as a line chart with flagged buckets drawn
in the same convention the BlackForge console uses; every other host sees exactly the JSON it
saw before.
Nothing about the tool contract changes. The chart payload travels in the result's _meta,
which is protocol metadata and reaches no model, so content[0].text is byte-identical
whether or not your host renders widgets, so the token cost of a series is the same either way.
That is deliberate: structuredContent would have been the obvious home for it, but core MCP
treats that field as server-produced result data, and a host without Apps support may hand it
to the model, doubling the cost of a large series.
The chart is one self-contained HTML file with uPlot and all CSS inlined, because MCP Apps
render under a deny-by-default CSP where an external <script> would simply never load. It is
read-only and never calls back into the server: it draws the points it was given and cannot
spend your row quota behind your back. Series longer than 2,000 points are decimated for the
chart only (the tool still returns every point), and the payload says so rather than
quietly thinning the line.
Data quality
When the API reports a row's measurement quality, blackforge_latest carries it through as a
quality object (flags naming what went wrong in the window, contaminates listing which
figures it flags) plus a plain-English qualityNote. blackforge_series
aggregates it into one qualitySummary ({ flaggedBuckets, of, flags }) rather than repeating
it on every point. Both keys are omitted entirely when nothing is flagged, and a
quality.raw of 32768 means the row predates the quality rail and was never assessed:
unknown, not bad. The flag decode table lives on the qualityFlags metric in
blackforge_catalog, as a bits array; this server reads it from there and never carries a
copy of its own.
Configuration
Local development
build runs tsup first and the widget's vite build second, and the order is load-bearing:
tsup's clean wipes the whole of dist/, so reversing them deletes the widget and leaves the
server serving a resource that is not there.
The integration test spawns the built server over stdio and drives it with the MCP client.
Its data assertions need a local BlackForge API at http://localhost:3001/api; without one,
those assertions are skipped and the tool-listing checks still run.
License
MIT
