BlackForge MCP Server
OfficialProvides real-time crypto market data including order-book depth, spreads, volumes, and liquidity metrics for trading pairs on Binance.
Provides real-time crypto market data including order-book depth, spreads, volumes, and liquidity metrics for trading pairs on Coinbase.
Provides real-time crypto market data including order-book depth, spreads, volumes, and liquidity metrics for trading pairs on KuCoin.
Provides real-time crypto market data including order-book depth, spreads, volumes, and liquidity metrics for trading pairs on OKX.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BlackForge MCP Serverget latest BTCUSDT on binance"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@blackforge-so/mcp
A Model Context Protocol stdio server that puts BlackForge market-data in your agent's hands. The whole crypto market, in real time — nine spot venues (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx) and every column it measures, per pair per closed 5-minute window.
Every column is a measurement with a definition — order-book depth and shape, resting
liquidity lifetimes, trade-explained vs book-implied volume, spreads, 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):
{
"mcpServers": {
"blackforge": {
"command": "npx",
"args": ["-y", "@blackforge-so/mcp"],
"env": { "BLACKFORGE_API_KEY": "bf_live_your_key" }
}
}
}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.
Related MCP server: Crypto Market Data MCP Server
Tools
Tool | Returns |
| Every venue and every column definition — 9 venues, and |
| The trading pairs a venue lists, e.g. |
| The latest completed 5-minute window for one |
| A time series for one column over a range: ascending |
| The key's recent request counts and remaining monthly row quota. |
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).
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 — 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
Env var | Default | Purpose |
| (none) | Your key. Required for every tool except |
|
| API base. Paths are appended as |
Local development
npm install
npm run build # → dist/index.js (ESM, executable) + dist/widget/chart.html
npm test # client unit tests + a stdio integration testbuild 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
Available Tools
5 toolsblackforge_catalogBlackForge catalogA
List every venue BlackForge covers (9 spot exchanges) and every column it measures (one wide row per (exchange, symbol) per 5-minute window: order-book depth and shape, resting-liquidity lifetimes, trade-explained vs book-implied volume, spreads, and market-wide context). metricCount is the exact number of columns available now. Each metric carries a precise measurement definition, unit, family, and the minimum plan that includes it; the qualityFlags metric also carries the bits table that decodes the per-row quality mask. This route needs no API key. CALL THIS FIRST to learn the exact exchange and metric identifiers the other tools accept.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It describes the tool as listing data and notes it needs no API key, but does not explicitly state read-only behavior. However, the 'list' verb implies safe operation, and the description provides sufficient detail about its output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but not overly long; it packs essential information about the output structure and usage. While it could be slightly more concise, every sentence serves a purpose, making it well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains what the tool returns: venues, columns, metric details including unit, family, plan, and additional info for qualityFlags. It also clarifies the data structure and the purpose of metricCount, making the tool's output fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline score is 4. The description adds value by explaining what the tool returns and how the identifiers relate to other tools, going beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists every venue and column BlackForge covers, which is a specific verb-resource combination. It distinguishes itself from siblings by being the initial discovery tool that provides identifiers for other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to 'CALL THIS FIRST' to learn exchange and metric identifiers for other tools, providing clear when-to-use guidance. It also notes that no API key is needed, which is a usage prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blackforge_latestBlackForge latest bucketA
Return the latest completed 5-minute window for one (exchange, symbol): a values object mapping each column key to its measured number (or null when not observed), plus the window timestamp ts in epoch milliseconds. Omit columns to get every column your plan includes; pass a subset of column keys (from blackforge_catalog) to narrow the payload. Columns your plan does not cover are dropped and reported in columnsOmitted so you can see why a key is absent. WHEN PRESENT, a quality object reports the row's measurement quality — flags names what went wrong during the window and contaminates lists which figures it flags, with a plain-English qualityNote beside it. Read it before trusting an unusual value. A quality.raw of 32768 means the row predates the quality rail and was never assessed — that is unknown, not bad. When the key is absent, the row carries no quality assessment at all.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Trading pair from blackforge_symbols, e.g. BTCUSDT. | |
| columns | No | Optional subset of column keys from blackforge_catalog. Omit for all plan-included columns. | |
| exchange | Yes | Venue identifier, e.g. binance. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: columnsOmitted for unsupported keys, quality object meaning (including raw=32768 meaning unknown), and an advisory to check quality before trusting values. This is thorough, though it could mention idempotency or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately verbose but well-structured: it leads with the core purpose, then details optional behavior, then explains the quality object. Each sentence serves a purpose, though some redundancy could be trimmed for even greater conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the return format: values object, columnsOmitted, and quality object with its sub-fields. It also covers edge cases (raw=32768, absent quality) and provides an action item ('Read it before trusting an unusual value'). This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds value by explaining that omitting columns returns all plan-included columns and that passing a subset narrows the payload, with reference to blackforge_catalog. This enriches the basic schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the latest completed 5-minute window for a specific exchange and symbol, providing output details (values object, ts, quality, columnsOmitted). This distinguishes it from sibling tools like blackforge_catalog (columns) and blackforge_symbols (symbols).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (get latest window) and how to narrow columns. However, it lacks explicit guidance on when not to use it or how it compares to alternatives like blackforge_series for historical windows, so usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blackforge_seriesBlackForge time seriesA
Return a time series for one column of one (exchange, symbol): points is an ascending array of { ts, value } where ts is epoch milliseconds and value is the measured number (or null). from/to are ISO-8601 datetimes; interval is one of 5m, 1h, 1d (higher intervals may be plan-gated). The server caps a response at 50,000 points. If the requested metric is above your plan, points comes back empty and the column is listed in columnsOmitted — that is why it is empty. WHEN ANY BUCKET IS FLAGGED, a qualitySummary object reports how many of the buckets carry a quality flag and which flags they are ({ flaggedBuckets, of, flags }); per-bucket quality is deliberately not repeated on every point. No qualitySummary means no bucket in the range was flagged.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End datetime, ISO-8601, e.g. 2026-07-02T00:00:00Z. | |
| from | Yes | Start datetime, ISO-8601, e.g. 2026-07-01T00:00:00Z. | |
| metric | Yes | Column key from blackforge_catalog, e.g. spreadMean. | |
| symbol | Yes | Trading pair, e.g. BTCUSDT. | |
| exchange | Yes | Venue identifier, e.g. binance. | |
| interval | Yes | Bucket size: 5m, 1h, or 1d. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses important behaviors: server caps response at 50,000 points, plan-gating results in empty points and columnsOmitted field, qualitySummary reporting, and that per-bucket quality is not repeated on each point. It does not mention rate limits or authentication requirements, but the disclosed behaviors are sufficient for an agent to understand the tool's boundaries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and structure. It is relatively long but each sentence adds unique information (output format, cap, plan gating, quality flags). It avoids redundancy with the schema (which already has param descriptions). Could be slightly more concise by combining some sentences, but overall it is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description adequately explains the return format (points array, columnsOmitted, qualitySummary). It covers edge cases (plan limitations, flagging) and the behavior of qualitySummary. It does not explicitly mention pagination or ordering beyond 'ascending array', but the 50,000 point cap addresses limits. The description is complete for a typical time series tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 6 parameters with 100% description coverage (each param has a description). The tool description adds value beyond the schema by explaining the output format (ascending array, {ts, value}), the meaning of columnsOmitted, the qualitySummary behavior, and the interval string format (e.g., 5m, 1h, 1d). This helps the agent understand how parameters map to results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a time series for one column of one (exchange, symbol). It specifies the output format (ascending array of {ts, value}), date range parameters, interval options, and plan-gating behavior. This distinguishes it from sibling tools like blackforge_latest (latest data point) or blackforge_catalog (available metrics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use the tool (when you need historical time series data for a specific metric), but it does not explicitly contrast with sibling tools (e.g., use blackforge_latest for single latest value, blackforge_catalog to discover metrics). No 'when not to use' or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blackforge_symbolsBlackForge symbolsA
List the trading pairs (symbols) a given venue trades, as an array of symbol strings. Use these values as the symbol argument to blackforge_latest and blackforge_series. Valid exchange values come from blackforge_catalog (e.g. binance, bybit, coinbase, kraken, okx). A venue outside the caller's plan returns HTTP 403 with the plan and an upgrade URL.
| Name | Required | Description | Default |
|---|---|---|---|
| exchange | Yes | Venue identifier from blackforge_catalog, e.g. binance, okx, coinbase. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses return type (array of symbol strings), error behavior (403 with plan/upgrade URL), and input constraints. Could mention idempotency or rate limits, but core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a clear purpose: action, usage guidance, and constraint info. No redundant words, well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one required parameter and no output schema, the description covers what, how, where to get input, and error handling. Sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes 'exchange' as venue identifier from blackforge_catalog. Tool description repeats this with more examples and reference to catalog. Since schema already covers the parameter fully, description adds marginal value, meeting baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List the trading pairs (symbols) a given venue trades', specifying the verb and resource. Distinguishes from siblings by explaining that output feeds into blackforge_latest and blackforge_series, and input comes from blackforge_catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use output as symbol argument for other tools and where to get valid exchange values (blackforge_catalog). Also mentions HTTP 403 on unauthorized venues, aiding in when-not-to-use. Lacks explicit exclusion of other uses, but sufficient for a list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
blackforge_usageBlackForge usageA
Report the calling key's recent usage: days is a per-day breakdown of request counts and the last request time, and rowsRemaining is the monthly row quota still available (omitted for usage-based plans that have no monthly ceiling). Use this to check headroom before a large pull.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals that 'rowsRemaining' is omitted for usage-based plans, a key behavioral detail. The tool is read-only ('Report'), which is implied but not explicit. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that are front-loaded with the primary action. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description provides sufficient detail about the two parts of the response ('days' and 'rowsRemaining') and the conditional omission. Complete for a simple usage tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not add param info. Schema coverage is 100% (vacuously). The baseline for 0 params is 4, and the description appropriately explains the output components.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Report the calling key's recent usage', providing a specific verb and resource. It distinguishes this usage tool from sibling tools like blackforge_catalog and blackforge_symbols, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool to 'check headroom before a large pull', giving clear context for when to invoke it. While it doesn't list alternatives, the unique purpose is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
blackforge_catalog - First observed
blackforge_latest - First observed
blackforge_series - First observed
blackforge_symbols - First observed
blackforge_usage
TDQS
Scored across 5 tools
Each tool has a distinct purpose: blackforge_catalog lists venues and metrics, blackforge_symbols lists trading pairs for an exchange, blackforge_latest returns the latest 5-minute window, blackforge_series returns historical data, and blackforge_usage reports API usage. No two tools overlap in functionality.
All tools follow a consistent pattern with the 'blackforge_' prefix and snake_case naming. The names are descriptive nouns or adjectives (catalog, symbols, latest, usage, series), maintaining uniform style.
Five tools effectively cover the essential operations for a financial data server: discovery, symbol listing, latest data, historical data, and usage tracking. The count is well-scoped and not excessive.
The tool surface provides comprehensive coverage: discover available metrics/exchanges, list symbols, retrieve latest window data, fetch time series, and monitor usage. No obvious gaps exist for the server's purpose.
Maintenance
Related MCP Connectors
Market intelligence for AI agents. Real-time data, cross-market analysis, and regime detection.
Agent-native crypto market-data over MCP+REST: order flow, whales, liquidations, calibrated scores
Open API Marketplace for AI Agents. Crypto data tools with USDC payments on Base.
Crypto market signals, technical indicators, and sentiment analysis for AI agents.
Related MCP Servers
- AlicenseBqualityBmaintenanceRead-only Hyperliquid data for AI agents: trades, fills, candles, funding, open interest, liquidations, wallet analytics and 12 months of fill history.32735 npmMIT
- AlicenseAqualityCmaintenanceProvides live cryptocurrency market data from over 100 exchanges, enabling AI agents to fetch prices, order books, funding rates, and more for trading analysis and arbitrage opportunities.132MIT
- AlicenseNot gradedqualityCmaintenanceAccess verified historical market data with quality flags, funding rates, and more, supporting micropayments for AI agents and trading bots.MIT
- AlicenseBqualityCmaintenanceReal-time crypto, stock, and prediction-market data for agents — prices, indicators, funding rates, DeFi TVL, macro calendar, and an AI momentum score. Configure one Base wallet key and it just works. No signup, no dashboard, no subscription.22208 npmMIT