com.bitcoincreditstack/mcp

Official12 tools

by JamieFrame · TypeScript

The Bitcoin credit markets, measured. Cross-venue rates, venue criteria, chain indicators.

com.bitcoincreditstack/mcp (MCP)

The com.bitcoincreditstack/mcp server is an Aletheia Analytics MCP interface that provides an agent-native access layer over the Gavel data product. It exposes Bitcoin credit markets data—such as cross-venue rates and venue criteria—along with Bitcoin on-chain indicators as MCP tools.

🛠️ Key Features

Covers Bitcoin credit markets “measured” data
Provides cross-venue rates
Supports venue criteria and chain indicators
Thin TypeScript wrapper around api.thegavel.io
Exposes Gavel credit data and Bitcoin on-chain indicators as MCP tools
12 tools available

🚀 Use Cases

Retrieve credit data and cross-venue rates for analysis
Evaluate venue criteria using Gavel-derived data
Use chain indicators alongside credit markets data

⚡ Developer Benefits

Avoids hand-rolling REST glue by using MCP tools
Intended for LLM-driven agents (e.g., Claude Desktop, IDE clients, custom agents)

⚠️ Limitations

Implementation details are constrained to the described wrapper around api.thegavel.io
Documentation excerpt references AI-concierge layers and indicator surfaces, without listing specific tool schemas

Captured live from the server via tools/list.

list_onchain_indicators

Returns the catalog of available on-chain indicator tools, including tool name, indicator name, brief description, units, an example invocation, and current readiness status ('live' or 'pending'). Use this when you need to discover which tools are available for on-chain analysis without inspecting every tool definition.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_mvrv

Returns the current Bitcoin MVRV ratio: market capitalisation divided by realised capitalisation, where realised cap values each coin at the price it last moved. MVRV is therefore an identity on observed chain data. It states the aggregate unrealised position of the supply — how far the market values coins above or below what was last paid for them — and nothing about what follows from that. This tool returns data; it does not advise, forecast, or characterise the market. Computed nightly from Aletheia's own full node and UTXO set. 'mvrv_z_score' is returned alongside it: the same numerator measured in standard deviations of the historical market-cap series. Returns: { value, mvrv_z_score, as_of, inputs: { market_cap_usd, realised_cap_usd, realised_price_usd, spot_price_usd }, methodology, disclaimer }.

Parameters1

timestamp

string

optional

ISO 8601 date. Currently ignored: the upstream serves the latest computed row only. Historical MVRV is available through get_gavel_indicator with include_history.

Raw schema

{
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "description": "ISO 8601 date. Currently ignored: the upstream serves the latest computed row only. Historical MVRV is available through get_gavel_indicator with include_history."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_indicators

Returns the catalogue of Aletheia indicators computed from The Gavel Protocol and the Bitcoin chain: id, name, family, units, description, and whether the indicator is currently live on this network. Three families: 'credit' (Gavel-derived assessments — the yield curve and the Bitcoin Credit Complex), 'onchain' (commodity chain metrics such as MVRV and SOPR), and 'market' (external context — DeFi rates, stablecoin supply, macro). Use this to discover what is available, then call get_gavel_indicator with an id. This tool returns a catalogue; it does not rank indicators or advise which to use.

Parameters2

family	string	optional	Restrict to one family. Omit to return the whole catalogue.
live_only	boolean	optional	If true, omit indicators that are not currently live on this network.

Raw schema

{
  "type": "object",
  "properties": {
    "family": {
      "type": "string",
      "enum": [
        "credit",
        "onchain",
        "market"
      ],
      "description": "Restrict to one family. Omit to return the whole catalogue."
    },
    "live_only": {
      "type": "boolean",
      "default": false,
      "description": "If true, omit indicators that are not currently live on this network."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_indicator

Returns the current value of a single Aletheia indicator by id, with its methodology reference. Call list_gavel_indicators first to discover valid ids. Optionally returns the historical series instead of the current value (set include_history). History is free and unmetered on the same terms as the current value. This is descriptive data; no recommendation is provided. An indicator that has no reading on this network says so explicitly rather than returning a null or a zero that could be mistaken for a value.

Parameters4

id	string	required	Indicator id from list_gavel_indicators, e.g. 'tci', 'ccpi', 'yield-curve', 'onchain-latest'.
include_history	boolean	optional	If true, return the historical series instead of the current value. Not every indicator has one.
from	string	optional	History start, ISO 8601 date. Only meaningful with include_history.
to	string	optional	History end, ISO 8601 date. Only meaningful with include_history.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Indicator id from list_gavel_indicators, e.g. 'tci', 'ccpi', 'yield-curve', 'onchain-latest'."
    },
    "include_history": {
      "type": "boolean",
      "default": false,
      "description": "If true, return the historical series instead of the current value. Not every indicator has one."
    },
    "from": {
      "type": "string",
      "description": "History start, ISO 8601 date. Only meaningful with include_history."
    },
    "to": {
      "type": "string",
      "description": "History end, ISO 8601 date. Only meaningful with include_history."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_verification_bundle

What can be checked about the contracts, and what did the last check return? Observations with their block heights; the verdict is the reader's. Contract addresses and their implementations, the bytecode hash of each, the upgradeability position, the privileged-function map with whether each can touch user funds, the audit reference, and five structural promises — each with the check that would falsify it and what that check returned. ⚠ Read the fields, not the impression. 'match' is "unchecked" where Aletheia has not compared deployed bytecode against verified source; a promise that did not settle says so; and mainnet and testnet return different answers because they run different builds. There is no safety score, rating or verified badge in this payload, and none will be added.

Parameters1

network

string

optional

Network. Default 'arbitrum-one' (mainnet). Use 'arbitrum-sepolia' for the testnet deployment, which carries a far deeper book — but note the two run different contract builds, so a testnet observation is not a mainnet fact.

Raw schema

{
  "type": "object",
  "properties": {
    "network": {
      "type": "string",
      "enum": [
        "arbitrum-one",
        "arbitrum-sepolia"
      ],
      "description": "Network. Default 'arbitrum-one' (mainnet). Use 'arbitrum-sepolia' for the testnet deployment, which carries a far deeper book — but note the two run different contract builds, so a testnet observation is not a mainnet fact."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_venues

Which credit venues does this dataset cover, and what is known about each? Returns the registry rows matching the filters you supply. One row per venue across four classes — on-chain protocols, CeFi desks, the corporate layer, and auction venues — each carrying its coverage state per pillar and how many of its criteria cells have been researched. Does not rank, score or order by any rate: rows are returned in the registry's own order. All filters are optional and unspecified means no constraint. ⚠ A venue's presence is not a statement about it. Coverage 'none' means nothing is ingested yet, which is a declared gap, not an observation about the venue.

Parameters5

venue_type	string	optional	Restrict to one class, e.g. 'onchain_pooled', 'cefi_desk', 'corporate_debt', 'auction'.
status	string	optional	Restrict by registry status: 'live', 'ingesting', 'registered', 'unresolved', 'defunct'.
chain_id	integer	optional	Restrict to venues on one EVM chain id.
complete_attributes_only	boolean	optional	Only venues whose criteria cells are fully researched (8 of 8). Default false.
limit	integer	optional	Cap the rows returned. Default 50. The response always states the unfiltered total.

Raw schema

{
  "type": "object",
  "properties": {
    "venue_type": {
      "type": "string",
      "description": "Restrict to one class, e.g. 'onchain_pooled', 'cefi_desk', 'corporate_debt', 'auction'."
    },
    "status": {
      "type": "string",
      "description": "Restrict by registry status: 'live', 'ingesting', 'registered', 'unresolved', 'defunct'."
    },
    "chain_id": {
      "type": "integer",
      "description": "Restrict to venues on one EVM chain id."
    },
    "complete_attributes_only": {
      "type": "boolean",
      "description": "Only venues whose criteria cells are fully researched (8 of 8). Default false."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Cap the rows returned. Default 50. The response always states the unfiltered total."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_venue

What is known about this venue, criterion by criterion? The three pillars — Price, Quality, Composition — each cell with its value and the source it came from. The criteria are published and versioned before any venue is measured against them, applied evenly to every row, and the spec version rides in this payload. There is no composite score, no stars and no reliability index: a reader weighs the criteria, and this server does not weigh them for the reader. ⚠ 'unknown' is a value, not an omission — a criterion that cannot be established from public sources says so with its reason. A class-specific 'not_applicable' and an unresearched 'unknown' are different answers and are never conflated.

Parameters1

venue_id

string

required

Registry id, e.g. 'aave_v3_arbitrum'. Call list_venues to discover valid ids.

Raw schema

{
  "type": "object",
  "properties": {
    "venue_id": {
      "type": "string",
      "description": "Registry id, e.g. 'aave_v3_arbitrum'. Call list_venues to discover valid ids."
    }
  },
  "required": [
    "venue_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compare_venues

What does credit at this tenor and LTV cost across every venue Aletheia covers? One row per venue in coverage-matrix order — no ranking, no default sort, no "best".

Parameters4

tenor_days	number	optional	Loan term in days to compare at.
ltv	number	optional	Loan-to-value as a decimal 0–1, not a percentage.
collateral	string	optional	Collateral asset symbol, e.g. 'BTC'.
denomination	string	optional	Loan denomination, e.g. 'USD'.

Raw schema

{
  "type": "object",
  "properties": {
    "tenor_days": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Loan term in days to compare at."
    },
    "ltv": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Loan-to-value as a decimal 0–1, not a percentage."
    },
    "collateral": {
      "type": "string",
      "description": "Collateral asset symbol, e.g. 'BTC'."
    },
    "denomination": {
      "type": "string",
      "description": "Loan denomination, e.g. 'USD'."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_credit_state

What does Bitcoin-collateralised credit cost and how much of it is outstanding, across the venues this dataset covers? One reading aggregated over the venue universe, not any single venue's book. Carries the term structure, outstanding quantity, valuation, collateral mix and quality composition, with the coverage block stating how many venues contributed and naming the ones that did not. No venue is weighted up, floated or reported under its own heading. ⚠ Read coverage before reading the figures. A venue absent from this reading is a declared gap, not a zero, and the rows it would have contributed are counted separately as unavailable.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_credit_state_history

How has the Bitcoin credit surface moved? The same cross-venue reading as get_credit_state, as a daily series. Each point carries the coverage that produced it, so a change in the series and a change in which venues were observable can be told apart. This is descriptive data; it does not forecast and it does not characterise a trend. ⚠ Coverage is not constant through the series. A move in a figure may be a move in the market or a venue entering or leaving observation — the per-point coverage is what distinguishes them.

Parameters1

days

integer

optional

How many days of history. Default 365, capped at 3650.

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "description": "How many days of history. Default 365, capped at 3650."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_market_composition

What kinds of credit make up this market, and in what proportions? ⚠ These series are computed from MORPHO BLUE ONLY, on Ethereum and Base. They are not market-wide. Composition by rate type, recourse and instrument, reported as observed shares with the scope that produced them. There is no ranking of venues or instrument types and no judgement about which composition is preferable. ⚠ The scope block names the contributing venues and states why the others are absent — Aave v3 is mid-backfill, Compound v3 and Sky are not yet ingested. Read it before quoting any share. A percentage from this tool describes one venue family, not Bitcoin-collateralised credit.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_market_flows

How much credit was created and retired, and over what period? Latest, trailing 30 days, and since inception. ⚠ These series are computed from MORPHO BLUE ONLY, on Ethereum and Base. They are not market-wide. Counts and amounts as observed, with the scope, coverage and validation state that produced them. Not a forecast, not a momentum signal, and not a characterisation of demand. ⚠ Creation and retirement are GROSS and are never netted into one signed series: a day of heavy churn and a quiet day can net to the same number and are not the same market. USD-denominated debt only.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md10 KBView on GitHub

gavel-mcp-server

Aletheia Analytics MCP server — agent-native interface over the Gavel data product.

Thin TypeScript wrapper around api.thegavel.io. Exposes Gavel credit data and Bitcoin on-chain indicators as MCP tools so LLM-driven agents (Claude Desktop, IDE clients, custom agents) can read the data product without hand-rolling REST glue.

Status

All three layers of the AI concierge spec (aletheia-docs data/specs/mcp/ai_concierge.md) are live, plus the indicator surface and real key→tier resolution. Delivered by Runbook R18 and governed by the decisions note data/specs/mcp/tier_and_scope_decisions_v1.md (MD1–MD12).

Layer A — read state

Tool	Upstream
`check_wallet_status`	direct RPC (balances, allowances, readiness blockers)
`find_auctions_matching_criteria`	`/v1/auctions`
`get_user_positions`	`/v1/user/:address/positions`
`get_loan_status`	`/v1/loans/:id/status`

Layer B — factory model (unsigned blueprints; the user signs)

Tool	Encodes
`prepare_bid_calldata`	`placeBid` + approval when allowance is short
`prepare_create_auction_calldata`	`createAuction` + collateral approval
`prepare_repay_loan_calldata`	`repayLoan` + repayment approval
`prepare_claim_collateral_calldata`	`claimCollateral`
`prepare_claim_refund_calldata`	`claimRefund`

Layer C — catalogues

Tool	Notes
`list_wallet_options`	static catalogue, no ranking
`recommend_fiat_onramp`	static catalogue; carries the two-purchase gas requirement

Data surface

Tool	Upstream
`list_gavel_indicators`	static catalogue of 32 indicators
`get_gavel_indicator`	`/v1/credit/`, `/v1/onchain/`, `/v1/market/*`
`get_yield_curve`	`/v1/yield-curve`
`get_mvrv`	`/v1/onchain/mvrv`
`get_protocol_reference`	static — addresses, signatures, conventions
`list_onchain_indicators`	static catalogue

The invariant

Aletheia builds; the user signs. There is no signing surface in this codebase — no wallet client, no account, no key material. viem is imported for encodeFunctionData only. That is what makes "Aletheia never signs" an architectural fact rather than a policy promise, and it must stay that way.

Equally load-bearing: no tool ranks, scores, or selects on the user's behalf. Filtering by user-supplied criteria is an information service; ranking by an internal model is investment advice. find_auctions_matching_criteria is named as it is deliberately, and the naming is not cosmetic.

Architecture

code

LLM Client → mcp.thegavel.io (this server) → api.thegavel.io (REST) → PostgreSQL
              [tool catalog, descriptions,        [authoritative endpoints]
               response shaping, auth, limits]

Single source of truth: the REST API. The MCP server never queries Postgres directly. Tools shape responses for LLM consumption (JSON-stringified text content) but never re-implement business logic. When the REST API upgrades, MCP inherits the upgrade automatically.

Local development

bash

# Install deps (Node 20+)
npm install

# Copy and edit env file
cp .env.example .env
nano .env  # set GAVEL_API_BASE_URL etc.

# Dev mode (tsx watch)
npm run dev

# Type check
npm run typecheck

# Build to dist/
npm run build

Point a development MCP client (MCP Inspector, Claude Desktop with an HTTP connector) at http://localhost:3002/mcp to exercise tools.

Deployment

Target: gavel-btc Hetzner host, alongside gavel-api.

bash

# Local — build and stage
npm install
npm run build

# Copy to server
scp -r dist/ package.json package-lock.json deployment/ \
    root@gavel-btc:/root/gavel-mcp/

# On server — install runtime deps (not the full dev set)
ssh root@gavel-btc
cd /root/gavel-mcp
npm install --omit=dev

# Configure
cp .env.example .env
nano .env
# Set:
#   GAVEL_API_BASE_URL=https://api.thegavel.io  (public API, for tool reads)
#   GAVEL_API_INTERNAL_URL=http://127.0.0.1:4012  (loopback, for tier lookup)
#   INTERNAL_API_SECRET=<must match gavel-indexer/.env.mainnet>
#   PORT=3002
#   NODE_ENV=production

# Install systemd unit
cp deployment/gavel-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable gavel-mcp.service
systemctl start gavel-mcp.service

# Verify
journalctl -u gavel-mcp -n 50 --no-pager
curl http://localhost:3002/health

# Reverse proxy
cp deployment/nginx-mcp.conf /etc/nginx/sites-available/mcp.thegavel.io
ln -s /etc/nginx/sites-available/mcp.thegavel.io \
      /etc/nginx/sites-enabled/mcp.thegavel.io
nginx -t && systemctl reload nginx

# TLS (Let's Encrypt)
certbot --nginx -d mcp.thegavel.io

# End-to-end check
curl https://mcp.thegavel.io/health

Configuration

All knobs live in .env:

Var	Default	Purpose
`PORT`	`3002`	HTTP listen port
`NODE_ENV`	—	`production` for JSON logs
`LOG_LEVEL`	`info`	pino level (`trace`/`debug`/`info`/`warn`/`error`)
`GAVEL_API_BASE_URL`	`http://localhost:3001`	Upstream REST base URL
`RATE_LIMIT_ANONYMOUS_PER_MINUTE`	`60`	Anonymous bucket size
`RATE_LIMIT_PAID_PER_MINUTE`	`300`	Paid bucket size
`CORS_ALLOWED_ORIGINS`	empty	Comma-separated; empty = no CORS
`HEALTH_CHECK_SECRET`	empty	If set, `/health` requires `?secret=...`
`GAVEL_API_INTERNAL_URL`	`http://127.0.0.1:4012`	Key→tier lookup. Must be the loopback address — `/internal/resolve-tier` refuses any request carrying an `X-Forwarded-For`, so the public `api.thegavel.io` host will not work
`INTERNAL_API_SECRET`	empty	Shared secret for the tier lookup. Must match `gavel-indexer/.env.mainnet`. Unset ⇒ every caller resolves to `free`
`MCP_TIER_ENFORCEMENT`	`false`	Enforce per-tool tiers. Leave `false` until Gate B — see Tier model
`ARBITRUM_RPC_URL`	public RPC	Chain reads for Layer A/B. Point at a paid endpoint in production
`ARBITRUM_SEPOLIA_RPC_URL`	public RPC	Testnet equivalent

Tier model

The ladder is free / pro / enterprise — identical to the product's (gavel-indexer/lib/tiers.js) and to what Stripe sells. The scaffold's original anonymous / developer / professional / enterprise was a second vocabulary for one entitlement and is retired (MD1).

gavel-indexer/lib/api-keys.js is the authority on what tier a key is. The MCP does not open its own database pool; it asks GET /internal/resolve-tier over loopback, caches the answer for 60 s, and fails open to free on any error. A data MCP that 500s because the key database hiccuped is worse than one that briefly serves anonymous.

Enforcement is authored but OFF

MCP_TIER_ENFORCEMENT defaults to false, and that is the correct state today. Monetisation is gated until Gate B (D16–D18): do not build a paywall until someone has asked to pay. Runbook A2 withdrew the commercial surface, and www.thegavel.io/pricing currently states that data access is free and open — so refusing a tool and pointing the user at a page which denies tiers exist would be a self-refuting journey.

With the flag off, requireTier still resolves the caller's real tier and logs what it would have refused. That log is the evidence for M6, the "has anyone actually asked to pay?" gate condition.

Before flipping it on, read MD2. There are two incompatible readings of what a paid MCP means — whole-surface-paid (lib/tiers.js carries mcp: false on free) versus depth-paid (MD3, the endorsed one). They are very different products.

What is free, and why

Per MD3, inheriting the D5 route/depth map: raw on-chain state, auction discovery, wallet status, commodity on-chain indicators, the current value of any Gavel-derived assessment, and history are all free. History is free because D9 retired the 30-day REST cap, and the MCP must not reintroduce a fence the surface it mirrors has abandoned. The paid boundary is bulk delivery, which this server does not offer.

Participation is never gated (D3). Every Layer A/B/C tool is free: a would-be bidder must never meet a paywall between deciding to bid and being able to.

Rate limits are infrastructure protection, not a billing meter (D2), and apply irrespective of the enforcement flag.

Redeploying a change

bash

npm run build            # tsc -> dist/ ; must be clean
systemctl restart gavel-mcp
systemctl is-active gavel-mcp
journalctl -u gavel-mcp -n 30 --no-pager

This service is systemd, not pm2. pm2 on this host carries quorum-mcp-testnet, a different service — pm2 restart gavel-mcp is a no-op that looks like a successful deploy. R18 v1 had this wrong; it is recorded in that runbook's §8.

The service runs dist/, not src/, so a change that is not built is a change that is not deployed.

Adding a tool

Create src/tools/<category>/<name>.ts. Copy credit/yield-curve.ts as the template — it's the cleanest worked example.
Define a Zod schema for inputs with .describe() on every field; that description is what the LLM sees during tool discovery.
Write the tool description as a multi-line string. Lead with what the indicator is, give interpretive context (without recommending anything), and document the response shape. The MCP SDK uses this verbatim in the catalog.
Body: requireTier(...) → upstreamGet(...) → return { content: [{ type: 'text', text: JSON.stringify(...) }] }.
Register the tool in src/tools/index.ts.
Add an entry to src/tools/discovery/list-onchain.ts (or the equivalent discovery catalog for that domain).

Testing manually

bash

# 1. Health
curl -s http://localhost:3002/health | jq

# 2. MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to http://localhost:3002/mcp
# Verify: tools/list returns 3 tools, get_yield_curve returns live data,
# get_mvrv returns a structured McpError "not found".

License

Install

Tools (12)

list_onchain_indicatorsget_mvrvlist_indicatorsget_indicatorget_verification_bundlelist_venuesget_venuecompare_venues

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.bitcoincreditstack.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.bitcoincreditstack.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

com.bitcoincreditstack/mcp (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

list_onchain_indicators

get_mvrv

list_indicators

get_indicator

get_verification_bundle

list_venues

get_venue

compare_venues

get_credit_state

get_credit_state_history

get_market_composition

get_market_flows

gavel-mcp-server

Status

The invariant

Architecture

Local development

Deployment

Configuration

Tier model

Enforcement is authored but OFF

What is free, and why

Redeploying a change

Adding a tool

Testing manually

License

Install

Remote endpoint

Related servers