Bitcoin Staking MCP

Bitcoin Staking MCP

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

Bitcoin Staking MCP combines current 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.

Architecture

flowchart LR
  A["Current production data"] --> C["Bitcoin Staking intelligence core"]
  T["Pre-production network data"] --> 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.

The answer policy is evidence-gated. The concierge may use only current MCP structured output and MCP resources for factual claims. It does not complete missing answers from model memory, infer wallet support from protocol behavior, treat an audit statement as end-to-end wallet proof, or substitute demo data after a live-read failure. When the corpus cannot answer a question, it says: “This MCP does not currently verify that,” and identifies the missing evidence.

Quick start

Requires Node 22.

Install for both Codex and Claude Code from any directory:

npx -y github:andre-stacks/bitcoin-staking-mcp setup

The installer performs a real MCP handshake, registers bitcoin-staking in the user-level configuration for both hosts, installs the global Codex concierge skill, and prints the first prompts. Restart both hosts after setup, then verify at any time:

npx -y github:andre-stacks/bitcoin-staking-mcp check

To install only one host, use --hosts codex or --hosts claude. See Installation for local-checkout, pinned-source, JSON, update, and uninstall options.

First conversation

Open $bitcoin-staking-concierge in Codex or /mcp__bitcoin_staking__bitcoin_staking_concierge in Claude Code. With no question attached, the concierge introduces itself and offers seven starting points: protocol status, bond discovery, participation fit, yield modeling, security diligence, compatibility or public status, and native-L1 versus sBTC comparison.

Choose a number or ask naturally. For example:

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

The single concierge command is the user-facing entry point. Eleven read-only MCP tools remain directly available to agents, developers, and MCP Inspector; users do not need to know their names.

For repository development:

npm ci
npm run check
npm start

For development:

npm run dev

Live data selection

Users do not need to choose a network. For a general opportunity or diligence question, the concierge:

1. checks verified mainnet state and published bond data;
2. uses that data when an opportunity is available;
3. otherwise checks the configured testnet automatically and labels it as a non-investable preview;
4. uses demo data only when the user explicitly requests an illustration.

This routing keeps the user experience stable: when a bond becomes published or available on mainnet, higher-precedence production data replaces the testnet preview without requiring different questions or prompts.

The current pre-production source is Hiro's dedicated PoX-5 testnet at https://api.testnet-pox5.hiro.so. Before activation, the server reports the activation schedule rather than inventing a bond. After activation, it returns only bonds proven on-chain and labels them testnet_only_not_investable.

For a complete state-aware proof—current status, opportunity routing, security evidence, demo fallback, no-match journey, and tool annotations—run:

npm run demo:proof

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/cli.js serve

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/cli.js serve

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

Tools

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

bitcoin-staking://capabilities maps the seven user-facing services to all eleven MCP tools.

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?

Which Bitcoin staking opportunities are currently available or coming next? Separate investable opportunities from pre-production data.

Build an institutional diligence report using the best currently available data. I have 1 BTC, require Bitcoin L1, want control of the maturity key, use Leather, and can lock for six months.

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
npm run demo:proof

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.

The offline suite invokes all eleven tools through an in-process MCP client, validates successful result metadata, checks network-specific manifest routing, exercises upstream failure behavior, and tests the shared prompt/skill abstention and voice contract. Prompt controls materially reduce unsupported answers, but no free-form host model can be guaranteed never to produce one; callers should treat returned provenance and explicit unknown states as the enforceable trust boundary.

Documentation

• Product requirements
• Installation
• Technical specification
• Hackathon delivery plan
• Security question catalog
• Institutional response standard
• Canonical source corpus
• Hackathon demo runbook
• Implementation audit
• User experience review

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.