# TBV Agents MCP Toolkit Guide

TBV Agents is a local-first toolkit for exploring the Trustless Bitcoin Vault protocol with software agents.

The current public surface is for public-testnet exploration, quoting, simulation, status inspection, faucet planning, and deterministic demo receipts. Mainnet BTC private-key handling is out of scope. Mainnet work should be limited to metadata, simulation, transaction-request preparation, and pre-signed transaction flow preparation until Babylon publishes a reviewed signing policy.

## What Agents Can Do Today

- Read network config, protocol parameters, wallet capability data, and signing boundaries.
- Quote a public-testnet peg-in.
- Simulate TBV flows without signing.
- Inspect flow specs for peg-in, borrow, repay, withdrawal, refund, and future mainnet preparation.
- Check faucet policy and build a faucet claim plan without bypassing Turnstile.
- Read redacted operation status and recent local public-testnet operation history.
- Use a local stdio MCP server from Claude, Codex, Cursor, or other MCP clients.
- Use the `tbv-agent` CLI as the deterministic execution source.

## MCP Command

For a packaged install:

```json
{
  "mcpServers": {
    "tbv-agents": {
      "command": "tbv-agent",
      "args": ["mcp", "serve"]
    }
  }
}
```

For a local checkout:

```json
{
  "mcpServers": {
    "tbv-agents": {
      "command": "node",
      "args": ["/absolute/path/to/bin/tbv-agent.js", "mcp", "serve"]
    }
  }
}
```

## Tool Groups

Read tools:

- `get_networks`
- `get_network_config`
- `get_protocol_params`
- `get_wallet_capabilities`
- `list_flows`
- `get_flow_spec`

Planning tools:

- `quote_pegin`
- `simulate_flow`
- `live_readiness`
- `toolkit_readiness`

Operational tools:

- `get_operation_status`
- `list_recent_operations`
- `faucet_status`
- `faucet_claim_plan`
- `agent_artifacts`

## CLI Commands

```bash
tbv-agent networks --json
tbv-agent status --network public-testnet --json
tbv-agent quote pegin --network public-testnet --amount 0.01btc --json
tbv-agent simulate-flow --flow pegin-aave-borrow-repay-withdraw --network public-testnet --amount 0.01btc --json
tbv-agent faucet claim-plan --signet-address tb1p... --sepolia-address 0x... --json
tbv-agent operations recent --json
tbv-agent readiness --json
tbv-agent mcp serve
```

## Safety Boundaries

- Do not ask users for raw mainnet BTC private keys.
- Do not send mainnet BTC private keys to hosted MCP or API services.
- Do not bypass wallet, hardware-wallet, smart-account, or custody approval.
- Do not automate Turnstile solving for faucet access.
- Public-testnet automation may use capped ephemeral wallets.
- Mainnet agent work should prepare transaction requests or pre-signed transaction flows for user execution.

## Current Public-Testnet Gaps

- Agent faucet path needs vouchers, allowlists, quotas, and signed receipts.
- Fresh-wallet peg-in completion needs stable public VP/VK/UC actor behavior.
- baby-tester packaging needs a public release or approved vendor/submodule policy.
- Hosted remote MCP/API should start read-only and reject private-key material.

## Machine-Readable References

- MCP manifest: `/mcp.json`
- OpenAPI: `/openapi.json`
- Agent card: `/.well-known/agent-card.json`
- Network config: `/tbv-network-config.json`
- Short instructions: `/llms.txt`
- Full instructions: `/llms-full.txt`