How do I install Gavel?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Gavel need an API key?

No required environment variable is listed on this record.

When was Gavel last checked?

Last checked 2026-11-08. The Bitcoin credit markets, measured. Cross-venue rates, venue criteria, chain indicators.

Gavel MCP server

Power your agent

Add this server

The publisher's own URL. Not a PlugMCP endpoint.

Add to Cursor Add in Claude Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Server URL

https://mcp.bitcoincreditstack.com/mcp

The Claude button above opens Claude with the name and URL filled in. You still confirm it there.

shClaude Code

1claude mcp add --transport http com.bitcoincreditstack-mcp https://mcp.bitcoincreditstack.com/mcp

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "com.bitcoincreditstack-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "mcp-remote",8        "https://mcp.bitcoincreditstack.com/mcp"9      ]10    }11  }12}

claude_desktop_config.json

Remote · HTTPPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Remote

Transport: http
Version: 0.1.0
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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

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

# 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.

# 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

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

# 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".

Gavel

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Gavel?

Does Gavel need an API key?

What transport does Gavel use?

When was Gavel last checked?

Documentation

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