Skip to main content
Glama
blackforge-so

BlackForge MCP Server

Official

@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

blackforge_catalog

Every venue and every column definition — 9 venues, and metricCount is the live column count. Keyless. Call this first to learn valid exchange and metric identifiers.

blackforge_symbols

The trading pairs a venue lists, e.g. ["BTCUSDT", …].

blackforge_latest

The latest completed 5-minute window for one (exchange, symbol) — a values object of column → number, with epoch-ms ts. Pass columns to narrow it.

blackforge_series

A time series for one column over a range: ascending { ts, value } points at 5m, 1h, or 1d. Capped at 50,000 points.

blackforge_usage

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

BLACKFORGE_API_KEY

(none)

Your key. Required for every tool except blackforge_catalog.

BLACKFORGE_BASE_URL

https://api.blackforge.so

API base. Paths are appended as /v1/.... Override for a self-hosted or local dev API (e.g. http://localhost:3001/api).

Local development

npm install
npm run build     # → dist/index.js (ESM, executable) + dist/widget/chart.html
npm test          # client unit tests + a stdio integration test

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

Available Tools

5 tools
blackforge_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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesTrading pair from blackforge_symbols, e.g. BTCUSDT.
columnsNoOptional subset of column keys from blackforge_catalog. Omit for all plan-included columns.
exchangeYesVenue identifier, e.g. binance.

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesEnd datetime, ISO-8601, e.g. 2026-07-02T00:00:00Z.
fromYesStart datetime, ISO-8601, e.g. 2026-07-01T00:00:00Z.
metricYesColumn key from blackforge_catalog, e.g. spreadMean.
symbolYesTrading pair, e.g. BTCUSDT.
exchangeYesVenue identifier, e.g. binance.
intervalYesBucket size: 5m, 1h, or 1d.

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
exchangeYesVenue identifier from blackforge_catalog, e.g. binance, okx, coinbase.

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 5 tool updatesv0.1.0
    • First observedblackforge_catalog
    • First observedblackforge_latest
    • First observedblackforge_series
    • First observedblackforge_symbols
    • First observedblackforge_usage

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    B
    maintenance
    Read-only Hyperliquid data for AI agents: trades, fills, candles, funding, open interest, liquidations, wallet analytics and 12 months of fill history.
    32
    735 npm
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Provides 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.
    13
    2
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Access verified historical market data with quality flags, funding rates, and more, supporting micropayments for AI agents and trading bots.
    MIT
  • A
    license
    B
    quality
    C
    maintenance
    Real-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.
    22
    208 npm
    MIT