Bitcoin Staking MCP

The agent-readable interface for discovering, understanding, and planning native Bitcoin staking on Stacks.

Bitcoin Staking MCP combines live mainnet and testnet PoX state, on-chain protocol-bond discovery, versioned bond manifests, deterministic yield scenarios, sourced security diligence, compatibility evidence, and a goal-first concierge. It is intentionally read-only: it cannot construct, sign, or broadcast transactions.

Why this exists

Bitcoin staking crosses Bitcoin L1, Stacks, wallets, custodians, economic assumptions, and product-specific enrollment rules. Agents need structured facts and explicit uncertainty—not another generic FAQ bot.

This server keeps four kinds of information separate:

• live: current chain or API state;

• published: public documentation or product metadata;

• derived: deterministic calculations or fit assessments;

• demo: synthetic hackathon data that is never presented as available capital infrastructure.

Related MCP server: Stacks AI MCP Server

Architecture

flowchart LR
  A["Stacks mainnet"] --> C["Bitcoin Staking intelligence core"]
  T["Configured PoX-5 testnet"] --> C
  B["Versioned bond manifests"] --> C
  C --> M["Read-only MCP server"]
  M --> X["Codex concierge skill"]
  M --> Y["Claude concierge prompt"]
  M --> Z["Any MCP client"]

The intelligence core contains schemas, provenance, economics, compatibility, and recommendation rules. It has no LLM dependency. The concierge is a thin workflow over MCP tools, not a separate service.

The concierge uses an institutional diligence voice: decision-first for CFO and investment audiences, mechanism-first for technical and custody teams, neutral rather than promotional, and explicit about uncertainty and the next verification step.

Quick start

Requires Node 22.

npm ci
npm run check
npm start

For development:

npm run dev

PoX-5 testnet proof

The default testnet target is Hiro's dedicated PoX-5 testnet at https://api.testnet-pox5.hiro.so. No additional configuration is needed:

npm start

Call get_protocol_status and list_protocol_bonds with network: "testnet". Before PoX-5 activation, the server returns the published activation height, countdown, and an empty bond list. After activation, it scans only the active bond window and returns configured records labeled testnet_only_not_investable. It never infers a bond merely because the network is named PoX-5.

The environment variables in .env.example can override the endpoint or chain ID for another compatible test network.

Codex

The repository includes .codex/config.toml and the repo-scoped $bitcoin-staking-concierge skill. Build the project, trust/open the repository in Codex, restart if needed, and inspect /mcp.

Manual configuration:

codex mcp add bitcoin-staking -- node /absolute/path/to/bitcoin-staking-mcp/dist/stdio.js

Then ask:

$bitcoin-staking-concierge I want yield, must keep BTC on Bitcoin L1, and can lock for six months.

Claude Code

The repository includes .mcp.json. Build the project, open Claude Code in the repository, approve the project MCP configuration, and verify:

claude mcp list

Invoke the server prompt:

/mcp__bitcoin_staking__bitcoin_staking_concierge

MCP Inspector

npx @modelcontextprotocol/inspector node dist/stdio.js

Use Inspector to review the instructions, all tool schemas and annotations, resources, prompt, valid calls, and error cases.

Tools

Resources expose the glossary, yield methodology, bond manifests, and source records under bitcoin-staking:// URIs.

bitcoin-staking://security exposes the complete security-diligence catalog. Security answers always distinguish published assurance, protocol/source behavior, SDK construction, wallet behavior, and end-to-end integration proof.

bitcoin-staking://methodology/sources exposes the source hierarchy and known corpus gaps. bitcoin-staking://methodology/response-standard exposes the institutional persona, audience adaptation, evidence language, and response contract.

Example prompts

What is the current Bitcoin Staking protocol status, and are any public bonds available?

On the configured testnet, which protocol bonds are currently open or approaching their start height? Make the testnet limitation explicit.

Has PoX-5 been audited, how is the Bitcoin timelock constructed, and what must I verify before signing the Leather transaction?

Include demo opportunities. I have 1 BTC, want native-L1 yield, control my keys, and can lock for 180 days. Show the assumptions and sources.

I want to borrow without selling and need access to my Bitcoin at any time. Compare the native Bitcoin staking path with sBTC context without recommending an unverified product.

Demo-data disclosure

data/bonds/demo-native-bitcoin-bond.json is synthetic. Its capacity, rate, fee, duration, eligibility, and compatibility fields are illustrative hackathon inputs. It has no on-chain bond index and is not open, published, investable, or available for enrollment.

Demo manifests:

• must carry dataStatus: "demo" and a demo source;

• are excluded by default;

• appear only in the separate demoBonds array when includeDemo: true;

• never override live or published data.

Validation

npm run typecheck
npm test
npm run build
npm run test:live
npm run test:testnet

The default tests are offline. The mainnet and configured-testnet tests are opt-in and read current public chain state. The checked-in concierge skill also passes the skill-creator quick validator. No command constructs or broadcasts a transaction.

Documentation

• Product requirements

• Technical specification

• Hackathon delivery plan

• Security question catalog

• Institutional response standard

• Canonical source corpus

Roadmap

1. Read-only MCP and public bond manifests.

2. Dedicated concierge UI and additional verified data adapters.

3. Operator/BD intelligence and unmet-demand reporting.

4. Separately approved, human-reviewed transaction preparation.

Safety boundary

This is experimental informational software, not financial advice. Verify every opportunity, wallet path, custody arrangement, economic assumption, and transaction through its authoritative source before committing capital.