@bsvkey/inference-mcp

An MCP server that lets any agent buy Claude & Grok inference metered per token, settled in BSV, through the hosted gateway at inference.bsvkey.com. Zero dependencies (Node ≥ 18, uses global fetch). It's a thin HTTP client — it never holds your keys or runs models; every call is billed through the gateway.

Tools: list_models, infer, channel_balance, open_channel, x402_infer, xrp_infer.

Two ways to pay: a prepaid channel (infer, fund once, draw down per token) or per call via x402 (x402_infer — no channel; the agent pays each request in BSV with its own key). x402_infer needs a funded WIF (wif arg or BSVKEY_WIF) and the optional @bsvkey/x402-bsv-client + @bsv/sdk packages (installed with this one).

Pay per call in XRP with xrp_infer: the tool gets a quote in XRP (priced from the XRP Ledger's own XRP/RLUSD market), signs one XRP Payment for exactly that locally, and the gateway checks it before broadcasting, waits for validation (a few seconds), and returns the answer, the settlement tx, and a signed receipt. It needs a funded XRP seed (xrpSeed arg or BSVKEY_XRP_SEED; create one at xrp.bsvkey.com/wallet) and the optional xrpl package (installed with this one; it needs Node 20.19+ or 22.12+). The account keeps a 1 XRP reserve that can't be spent.

Verifiable metering. Each infer call returns a signed usage receipt, and the tool auto-verifies it offline (with the optional packages installed): the result includes receiptVerified and meterVerified (true, false + receiptCheck, or null). It recovers the broker key (pinned from GET /v1/receipt-key); binds the receipt to the channel you called (from your API key, not the receipt's self-report); checks a monotonic sequence (no replay/gap) and running totals within the funded amount; recomputes the charge from the published rate (you can never be overcharged); and recomputes the token count from the exact bytes of your messages and the completion, under the pinned bsvkey-meter/1 tokenizer. So the channel payment is on-chain and both the meter and the charge are auditable, without trusting the broker's word.

Four things an unattended client should know:

• Fails closed. If the pinned-key endpoint is unreachable, receiptVerified is null (unknown), never true — a down pin weakens the check to unknown, not to trusted.

• Supply your funded amount. Set BSVKEY_FUNDED_SATS (or pass fundedSats) to the amount you funded on-chain. The receipt's own fundedSats is the broker's assertion; when you supply yours, a receipt claiming a different amount is rejected and totals are checked against what you actually paid.

• Persist across restarts. Sequence continuity is in-memory by default (a replay before the first receipt this process sees would be invisible). Set BSVKEY_RECEIPT_STATE to a file path to persist per-channel seq/totals so replays are caught across restarts.

• The receipt is the ledger. The GET /v1/channels/:id balance endpoint can lag the signed receipt by ~20s; trust the receipt, treat the endpoint as a cache.

Spec: https://inference.bsvkey.com/usage-receipts.md

Quick start

1. Fund a channel once at https://inference.bsvkey.com (BRC-100 wallet, or load a key in-page). Copy the key it returns: channelId:channelSecret.

2. Add the MCP server to your agent host (below), with that key in BSVKEY_API_KEY.

3. Ask your agent to run inference — it calls infer and pays per token.

list_models and open_channel work with no key; infer and channel_balance need a funded channel key.

Related MCP server: x402-gateway-mcp

Install

Published on npm as @bsvkey/inference-mcp.

Claude Code

claude mcp add bsvkey-inference \
  --env BSVKEY_API_KEY=channelId:channelSecret \
  -- npx -y @bsvkey/inference-mcp

Claude Desktop / Codex / any MCP host (JSON config)

{
  "mcpServers": {
    "bsvkey-inference": {
      "command": "npx",
      "args": ["-y", "@bsvkey/inference-mcp"],
      "env": { "BSVKEY_API_KEY": "channelId:channelSecret" }
    }
  }
}

No npm? Grab the single-file server directly (https://inference.bsvkey.com/mcp/server.js) and use "command": "node", "args": ["server.js"].

Hosted (no install)

Any MCP host that supports remote servers can connect to https://inference.bsvkey.com/mcp (Streamable HTTP). Same six tools, nothing to install.

claude mcp add --transport http bsvkey-inference https://inference.bsvkey.com/mcp \
  --header "Authorization: Bearer channelId:channelSecret"

{
  "mcpServers": {
    "bsvkey-inference": {
      "type": "http",
      "url": "https://inference.bsvkey.com/mcp",
      "headers": { "Authorization": "Bearer channelId:channelSecret" }
    }
  }
}

• list_models and open_channel need no header.

• infer and channel_balance use the prepaid channel key in the Authorization header (or apiKey per call).

• The hosted server never takes a private key. x402_infer (Bitcoin BSV) and xrp_infer (XRP) are two steps there: call without payment to get the quote, sign it in your own wallet, then call again with payment (the base64 X-PAYMENT value). A wif or xrpSeed argument is refused.

• The hosted server returns the signed usage receipt but does not verify it for you; verify it offline with @bsvkey/x402-bsv-client. To sign payments and verify receipts locally from a key, use the npm package above.

Configuration (env)

Errors

A failed tool call returns isError: true with text in one fixed shape, so an agent can branch on the code without parsing prose:

error: <code> (<http status>): <message> [extra=value, ...]

On a prepaid channel nothing is charged on any error. A successful infer can still report receiptVerified: false (the signed receipt didn't check out; see receiptCheck) or null (couldn't check: verifier missing, or the receipt-key endpoint was down).

Thinking models (claude-sonnet-5, claude-opus-5, claude-opus-5-5, claude-fable-5-1) bill their hidden reasoning as output, and maxTokens is raised to at least 1024 for them.

Verify it's wired (no key needed)

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_models","arguments":{}}}' \
  | node server.js

Marketplace listing blurb

BSV Inference — Pay-per-token Claude & Grok, settled in BSV. Prepay a channel once, then meter every token with no subscription, account, or card. OpenAI- compatible, optional live web search, on-chain settlement. MCP + portable SKILL.md.

Publishing (operator)

• Live on npm under the @bsvkey org (owner: interence). First publish: v1.0.0.

• To ship an update: bump version in package.json, then npm publish --access public (2FA/security-key prompt applies).

• Canonical source: https://github.com/BSVKey/inference-mcp

• To list on a skills marketplace (e.g. bopen.ai), submit SKILL.md + this README.