# Connect your AI tool with MCP

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Give Claude Code the BSV blockchain docs and the @bsv/mcp tools through MCP servers, so your agent reads these pages, checks BSV Broadcaster and reviews your project on testnet.

import McpServers from '/snippets/McpServers.jsx';

Connect [Claude Code](https://code.claude.com/docs/en/overview) to the BSV blockchain docs and tools through MCP, the [Model Context Protocol](https://modelcontextprotocol.io/) an AI tool uses to call an outside server for information. With them, your agent searches and reads these pages before it writes code for the BSV blockchain, and checks transactions and projects with those tools. Use it when an AI agent builds your BSV blockchain app. Without a source, the agent can pick the wrong network or put a private key in your code. At the end, the docs server and `@bsv/mcp` are connected to your project, and the agent has checked a project against the BSV blockchain guardrails.

## Before you begin

- [Claude Code](https://code.claude.com/docs/en/overview) installed. This guide was tested with Claude Code 2.1.303.
- Node.js 22 or newer, for `@bsv/mcp`, which runs through `npx`.

## How it works

Two MCP servers give the agent knowledge of the BSV blockchain in different ways. The BSV blockchain docs server runs at `https://bsvblockchain.com/docs/mcp`, and `@bsv/mcp` is a package that runs on your machine:

<McpServers />

- BSV blockchain docs server: gives search and full pages of these docs, as Markdown. Use it for answers and code that follow these guides, starting on testnet.
- `@bsv/mcp`: gives tools for BSV Broadcaster (formerly Arcade), a guardrail check, BRCs and versions, with dated facts. Use it for actions and live values, on testnet by default.

Claude Code adds each server to the current project only, so run the commands in your project folder.

> The `bsv-dev` plugin of [Install the BSV blockchain agent skill](https://bsvblockchain.com/docs/build-with-ai/skill/) already connects both servers, as `plugin:bsv-dev:bsv-docs` and `plugin:bsv-dev:bsv-mcp`. With the plugin, skip the two `claude mcp add` commands on this page, or Claude Code starts a second copy of `bsv-mcp`. The tools, the guardrail check and the settings below are the same.

## Connect the BSV blockchain docs server

The docs server runs on this site and needs no login or API key:

**1. Add the server**

Add the server under the name `bsv-docs`:

```bash
claude mcp add --transport http bsv-docs https://bsvblockchain.com/docs/mcp
```

```text
Added HTTP MCP server bsv-docs with URL: https://bsvblockchain.com/docs/mcp to local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]
```

The name is the one Claude Code shows for the server. Keep `bsv-docs`, since the `bsv-dev` rules and the skill look for the server under that name.

**2. Check the connection**

List the servers in the project:

```bash
claude mcp list
```

```text
Checking MCP server health…

bsv-docs: https://bsvblockchain.com/docs/mcp (HTTP) - ✔ Connected
```

The agent now has three tools to read the docs:

| Tool | What it does |
|------|--------------|
| `list_docs` | Lists every page with its title, path, address and description |
| `search_docs` | Searches the docs by keywords and returns the best matching pages with a snippet of each, 5 by default and up to 20 |
| `get_doc` | Returns one or more pages in full, as Markdown, by path or address |

Ask Claude Code a question about the BSV blockchain in the same project, and it calls `search_docs` and `get_doc` before it answers. For a first payment, the docs lead the agent to [Send a payment from a web app](https://bsvblockchain.com/docs/get-started/quick-start-browser/), where a testnet wallet in [BSV Desktop](https://desktop.bsvb.tech/) approves the payment and no private key goes in your code.

> The page addresses in the results use `bsvblockchain.com/docs`. To read a page, the agent passes its path to `get_doc`, which works with or without the site address.

## Add @bsv/mcp

`@bsv/mcp` is BSV Association's MCP server for building apps, testnet first. Its source is in [bsv-blockchain/bsv-ai-toolkit](https://github.com/bsv-blockchain/bsv-ai-toolkit). It replaces `@bsv/simple-mcp`, as described in [Where Simple MCP went](#where-simple-mcp-went). This section uses `@bsv/mcp` 2.0.1.

**1. Add the server**

Add the server under the name `bsv-mcp`, on testnet:

```bash
claude mcp add bsv-mcp -e BSV_NETWORK=testnet -- npx -y @bsv/mcp
```

```text
Added stdio MCP server bsv-mcp with command: npx -y @bsv/mcp to local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]
```

Testnet is the default, and `BSV_NETWORK=testnet` keeps the network visible in the configuration. Claude Code starts the server through `npx`, which downloads the package the first time.

**2. Check the connection**

List the servers again:

```bash
claude mcp list
```

```text
Checking MCP server health…

bsv-docs: https://bsvblockchain.com/docs/mcp (HTTP) - ✔ Connected
bsv-mcp: npx -y @bsv/mcp - ✔ Connected
```

The agent now has ten tools. The four `broadcaster_*` tools work with BSV Broadcaster (formerly Arcade), whose public endpoint hostnames still contain `arcade`:

| Tool | What it does |
|------|--------------|
| `broadcaster_submit` | Broadcasts a signed transaction, as raw or EF (Extended Format (BRC-30): the raw transaction plus the satoshis and locking script of every output it spends) hex, to BSV Broadcaster and reads its status back. It refuses BEEF (Background Evaluation Extended Format (BRC-62): a transaction with the evidence a host needs to verify it). On Mainnet it also needs `BSV_MCP_ALLOW_MAINNET_BROADCAST=1` |
| `broadcaster_status` | Reads the status of a transaction from BSV Broadcaster and says whether it is final for an app: `SEEN_ON_NETWORK` or later with no competing transaction |
| `broadcaster_policy` | Reads the fee rate and the size limits of a BSV Broadcaster endpoint |
| `broadcaster_health` | Reads the version, block height and upstream nodes of a BSV Broadcaster endpoint |
| `check_guardrails` | Checks a project against the BSV blockchain guardrails `G-01` to `G-38` and lists each finding with its fix. It reads the project and changes nothing |
| `brc_lookup` | Returns a BRC as Markdown, by number |
| `versions_check` | Compares the pinned package versions, the Rúnar commit and the BSV Broadcaster version of each known endpoint with the latest ones |
| `docs_url` | Finds the live address of a page of these docs from its id |
| `code_search`, `find_function_definition` | Search local clones of the BSV blockchain repositories, made with `setup.sh` from the repository, in the folder set in `BSV_REPOS_DIR` |

The server also has 16 resources for the agent to read. Ten are dated facts, `bsv://facts/*`, on networks, BSV Broadcaster (`bsv://facts/bsv-broadcaster`), fees, WhatsOnChain, wallet limits, consensus, Rúnar, 1Color tokens, payment channels (Two parties lock funds in one output and exchange signed updates off the network. Only the last update is broadcast) and versions. Each fact starts with the date it was verified, so the agent can tell how current it is. The other six are the guardrails, `bsv://guardrails`, the custody shapes, the threat model, the docs index, and the `@bsv/simple` 0.7 API and its traps. Two templates read one guardrail, as `bsv://guardrails#G-09` for example, and any BRC, as `bsv://brc/{id}`.

It also has five prompts: `review_against_guardrails` runs the guardrail check and fixes the errors, `tokenize_with_1color` gives the encoding of 1Color token outputs, and `integrate_simple`, `add_simple_feature` and `debug_simple` work with `@bsv/simple`.

> `broadcaster_submit` refuses a Mainnet broadcast, before it contacts BSV Broadcaster, unless `BSV_MCP_ALLOW_MAINNET_BROADCAST=1` is set in the shell that starts the agent. The gate goes by the network of the call, never by the address: the `network` the agent passes, or `BSV_NETWORK` when it passes none. A custom `BSV_BROADCASTER_URL` that points at Mainnet needs `BSV_NETWORK=mainnet`. Under `BSV_NETWORK=testnet`, the server treats that endpoint as testnet, and the gate does not apply. A Mainnet broadcast spends real BitcoinSV (BSV) and cannot be undone.

## Check a project against the guardrails

The guardrails are the rules a BSV blockchain app follows, such as broadcasting through BSV Broadcaster and keeping keys in the wallet. `check_guardrails` is the quickest tool to try, since it needs no wallet and no coins:

**1. Ask for the check**

In Claude Code, in your project folder, type the request:

```text
Check this project against the BSV guardrails.
```

The agent calls `check_guardrails` with the absolute path of the project. The tool refuses a relative path.

**2. Read the report**

The report starts with the number of errors and warnings, then lists each finding with its guardrail, file and line, the fix, and a reference to the guardrail. For a project that broadcasts through the `ARC` class of the SDK, it looks like this, shortened:

```text
check_guardrails: 15 errors, 5 warnings, shape A
...
error G-09 src/broadcast.ts:6  export const arc = new ARC('https://arc.taal.com', { deploymentId: 'tipjar' })
  fix: Broadcast only through BSV Broadcaster (`POST /tx`, text/plain, EF when sources are attached, never BEEF); never the SDK `ARC` class or `/v1/tx`; `BSV_BROADCASTER_URL` configurable with the public instance per network as default. (bsv://guardrails#G-09)
...
passed: G-04
not applicable: G-08, G-17, G-18, G-19, G-23, G-24, G-36
manual checklist: G-05, G-07, G-11, G-13, G-20, G-22, G-26, G-27, G-28, G-29, G-30, G-32, G-33, G-35, G-37, G-38
```

G-09 is the rule to broadcast only through BSV Broadcaster, and the `ARC` class calls a path BSV Broadcaster does not serve. An `error` is a finding to fix, and a `warn` is one to check. `shape A` means the user's wallet holds the keys. A guardrail is not applicable when the project has nothing it covers. The tool cannot check the guardrails in the manual checklist from the code, so the agent reviews those by hand.

For payment channels, the tool checks G-36 in the code: every lock time is in seconds or a block height, never in milliseconds. The other channel guardrails, G-35, G-37 and G-38, are in the manual checklist. The tool also checks G-08 in the code, a rule for any app that signs a digest: the app signs only a digest it rebuilt itself, never one it received over the wire.

A project is ready when the report shows 0 errors. The repository's tipping sample, [`samples/tipping-shape-a`](https://github.com/bsv-blockchain/bsv-ai-toolkit/tree/main/samples/tipping-shape-a), reports `0 errors, 0 warnings`, as [Start from the tipping sample](https://bsvblockchain.com/docs/build-with-ai/tipping-sample/) shows. To keep a finding that you checked and accept, add `// bsv-guardrail-ignore GUARDRAIL_ID REASON` on the flagged line or the line above. Replace `GUARDRAIL_ID` with the id of the guardrail, such as `G-09`, and `REASON` with why you accept the finding. In a file with other comments, start it with `#`, `<!--` or `/*` instead of `//`. Every guardrail is listed in [`content/guardrails.yaml`](https://github.com/bsv-blockchain/bsv-ai-toolkit/blob/main/content/guardrails.yaml).

## Set the environment

`@bsv/mcp` reads these variables, which you pass with `-e` in `claude mcp add`. The plugin sets `BSV_NETWORK` and `BSV_BROADCASTER_URL` from its `bsv_network` and `broadcaster_url` settings:

| Variable | Default | What it does |
|----------|---------|--------------|
| `BSV_NETWORK` | `testnet` | `testnet` or `mainnet`. Picks the default BSV Broadcaster endpoint and gates Mainnet broadcasts. Any other value stops the server |
| `BSV_BROADCASTER_URL` | Per network | BSV Broadcaster base URL. Default on testnet `https://arcade-v2-testnet-us-1.bsvblockchain.tech`, on Mainnet `https://arcade-us-1.bsvblockchain.tech`. A host that belongs to the other network stops the server |
| `BSV_MCP_ALLOW_MAINNET_BROADCAST` | Not set | `1` lets `broadcaster_submit` broadcast on Mainnet |
| `BSV_REPOS_DIR` | Not set | The folder of BSV blockchain repository clones made with `setup.sh`, for `code_search` and `find_function_definition` |

The server still reads `ARCADE_URL`, the former name of `BSV_BROADCASTER_URL`, when `BSV_BROADCASTER_URL` is not set. It is deprecated, and the server logs a warning when it uses it.

Set `BSV_NETWORK=mainnet` for any Mainnet BSV Broadcaster endpoint, including your own. The server goes by the network you set, not by the address: it refuses the known Mainnet hosts on testnet, but it cannot tell where an unknown host belongs, so it treats an unknown Mainnet endpoint under `BSV_NETWORK=testnet` as testnet, without the Mainnet gate.

The testnet default is the host that [Broadcast transactions with BSV Broadcaster](https://bsvblockchain.com/docs/guides/services/broadcasting/) uses. `arcade-testnet-us-1`, the default of `@bsv/mcp` 2.0.0, still works and counts as testnet; set `BSV_BROADCASTER_URL` to use it.

## Use another AI tool

Cursor, Windsurf and VS Code take the same two servers as JSON. Each configuration adds both servers; remove the `bsv-mcp` entry if you want only the docs:

**Cursor**

Add to `.cursor/mcp.json`:

```json .cursor/mcp.json
{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "@bsv/mcp"],
      "env": { "BSV_NETWORK": "testnet" }
    },
    "bsv-docs": {
      "url": "https://bsvblockchain.com/docs/mcp"
    }
  }
}
```

**Windsurf (Devin Desktop)**

Windsurf is now named Devin Desktop. Add to `~/.config/devin/mcp_config.json` on macOS and Linux, or `%APPDATA%\devin\mcp_config.json` on Windows, as its [MCP documentation](https://docs.devin.ai/desktop/cascade/mcp) says. It names the URL field `serverUrl`:

```json ~/.config/devin/mcp_config.json
{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "@bsv/mcp"],
      "env": { "BSV_NETWORK": "testnet" }
    },
    "bsv-docs": {
      "serverUrl": "https://bsvblockchain.com/docs/mcp"
    }
  }
}
```

**VS Code**

Add to `.vscode/mcp.json`. VS Code uses a top-level `servers` key instead of `mcpServers`:

```json .vscode/mcp.json
{
  "servers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "@bsv/mcp"],
      "env": { "BSV_NETWORK": "testnet" }
    },
    "bsv-docs": {
      "type": "http",
      "url": "https://bsvblockchain.com/docs/mcp"
    }
  }
}
```

These configurations come from the install notes of `@bsv/mcp` and were not run for this guide.

## Remove a server

Run `claude mcp remove` with the name of the server, in the project folder where you added it. `-s local` is the scope that `claude mcp add` uses. To remove both servers, for example before you install the plugin:

```bash
claude mcp remove bsv-docs -s local
claude mcp remove bsv-mcp -s local
```

```text
Removed MCP server bsv-docs from local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]
Removed MCP server bsv-mcp from local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]
```

## Where Simple MCP went

`@bsv/mcp` replaces `@bsv/simple-mcp`. The table below shows where each resource and prompt went. If your project still has `@bsv/simple-mcp`, remove it with `claude mcp remove simple-mcp -s local` and add `@bsv/mcp` as above.

**Resources and prompts that moved**

| `@bsv/simple-mcp` 0.0.2 | `@bsv/mcp` 2.0.1 |
|---|---|
| `simple://api/*`, `simple://guide/nextjs`, `simple://guide/patterns` | Resource `bsv://simple/api` |
| `simple://guide/gotchas` | Resource `bsv://simple/gotchas` |
| Prompt `integrate_simple` | Prompt `integrate_simple` |
| Prompt `add_bsv_feature` | Prompt `add_simple_feature` |
| Prompt `debug_simple` | Prompt `debug_simple` |
| `scaffold_nextjs_config` and the `generate_*` tools | None |

The code generators have no replacement. The prompts guide the agent to write the code itself, testnet first.

## Next steps

With both servers connected, give the agent the BSV blockchain playbook, which in Claude Code replaces these servers with the plugin's, then let it build a first payment:

- [Install the BSV blockchain agent skill](https://bsvblockchain.com/docs/build-with-ai/skill/)
- [Send a payment with an AI agent](https://bsvblockchain.com/docs/build-with-ai/prompts/)
- [Broadcast transactions with BSV Broadcaster](https://bsvblockchain.com/docs/guides/services/broadcasting/)