> For the complete documentation index, see [llms.txt](https://hub.bsvblockchain.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.bsvblockchain.org/bsv-code-academy/bsv-simple/simple-sdk/mcp-server.md).

# MCP Server

`@bsv/simple` ships with a companion **Model Context Protocol (MCP) server** that gives AI coding assistants (Claude Code, Cursor, Copilot, etc.) structured knowledge about the library and the ability to generate integration code.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI tools connect to external knowledge and capabilities. An MCP server exposes:

* **Resources** — read-only knowledge the AI can consult
* **Tools** — functions the AI can call to generate code
* **Prompts** — pre-built conversation templates for common workflows

## Available Resources

| URI                          | Description                                                  |
| ---------------------------- | ------------------------------------------------------------ |
| `simple://api/wallet`        | WalletCore, BrowserWallet, and ServerWallet method reference |
| `simple://api/tokens`        | Token create, list, send, redeem, and MessageBox transfer    |
| `simple://api/inscriptions`  | Text, JSON, file-hash, and image-hash inscriptions           |
| `simple://api/messagebox`    | MessageBox certification, payments, and identity registry    |
| `simple://api/certification` | Certifier class and certificate management                   |
| `simple://api/did`           | DID class and wallet DID methods                             |
| `simple://api/credentials`   | Schema, Issuer, Verifiable Credentials/Presentations         |
| `simple://api/overlay`       | Overlay networks, SHIP/SLAP, broadcasting                    |
| `simple://guide/nextjs`      | Complete Next.js integration guide                           |
| `simple://guide/gotchas`     | Critical pitfalls and non-obvious behaviors                  |
| `simple://patterns`          | Common code patterns and recipes                             |

## Available Tools

| Tool                           | Parameters                               | Description                                            |
| ------------------------------ | ---------------------------------------- | ------------------------------------------------------ |
| `scaffold_nextjs_config`       | `features: string[]`                     | Generate `next.config.ts`, package.json additions      |
| `generate_wallet_setup`        | `target`, `framework`                    | Wallet initialization code (browser or server)         |
| `generate_payment_handler`     | `type`, `basket?`                        | Payment handler (simple, multi-output, server-funding) |
| `generate_token_handler`       | `operations: string[]`                   | Token handler functions                                |
| `generate_inscription_handler` | `types: string[]`                        | Inscription handler functions                          |
| `generate_messagebox_setup`    | `features: string[]`, `registryUrl?`     | MessageBox integration code                            |
| `generate_server_route`        | `actions: string[]`, `walletPersistence` | Next.js API route handler                              |
| `generate_credential_issuer`   | `schemaFields`, `revocation`             | CredentialIssuer setup code                            |
| `generate_did_integration`     | `features: string[]`                     | DID integration code                                   |

## Available Prompts

| Prompt             | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `integrate_simple` | Full walkthrough for adding `@bsv/simple` to a project        |
| `add_bsv_feature`  | Generate code for a specific feature (payments, tokens, etc.) |
| `debug_simple`     | Debugging help with common gotchas checklist                  |

## Installation

### Claude Code (recommended)

```bash
claude mcp add simple-mcp -- npx -y @bsv/simple-mcp
```

That's it — Claude will automatically download and run the MCP server via npx.

### With Docker

```bash
# Build
docker build -t simple-mcp simple-mcp/

# Run (stdio transport)
docker run -i --rm simple-mcp
```

### Without Docker

```bash
cd simple-mcp
npm install
npm run build
npm start
```

## Configuring Claude Code

Add the MCP server to your Claude Code settings:

```json
// ~/.claude/settings.json
{
  "mcpServers": {
    "simple": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "simple-mcp"]
    }
  }
}
```

Or for local development:

```json
{
  "mcpServers": {
    "simple": {
      "command": "node",
      "args": ["/path/to/simple-mcp/dist/index.js"]
    }
  }
}
```

## Example Usage

Once connected, you can ask your AI assistant things like:

* "Set up @bsv/simple in my Next.js project"
* "Generate a payment handler"
* "Create a token system with MessageBox transfer"
* "Add verifiable credential issuance to my server"

The AI will consult the MCP resources for accurate API information and use the tools to generate working code that follows the library's patterns.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hub.bsvblockchain.org/bsv-code-academy/bsv-simple/simple-sdk/mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.