# MCP server

Coinset runs a **read-only [Model Context Protocol](https://modelcontextprotocol.io) server** that
lets AI agents (Claude, Cursor, and anything else that speaks MCP) query the Chia blockchain through
Coinset — balances, transactions, coins, assets, offers, blocks, the mempool, fees, and live price,
plus local CLVM and offer tooling.

It is **read-only**: no keys, no signing, no `push_tx` / `push_offer`. A single endpoint serves both
**mainnet** and **testnet11** — you pick the network per request.

**Endpoint:** `https://mcp.coinset.org/`

## Quick start

1. Add the server to your MCP client config (see below).
2. Reconnect / reload MCP in your client.
3. Ask a question, e.g. *"What's the XCH balance of `xch1…`, in USD?"*

## Connect your client

The server speaks the **Streamable HTTP** MCP transport. The URL is always
`https://mcp.coinset.org/`.

### Cursor

Create or edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "coinset": {
      "url": "https://mcp.coinset.org/"
    }
  }
}
```

Then enable / refresh **coinset** under Settings → MCP.

### Claude Code

```bash
claude mcp add --transport http coinset https://mcp.coinset.org/
```

### Claude Desktop

Claude Desktop currently speaks stdio, so front the URL with a remote shim in
`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "coinset": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.coinset.org/"]
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "coinset": {
      "type": "http",
      "url": "https://mcp.coinset.org/"
    }
  }
}
```

### Anything else that speaks MCP

Point it at the Streamable HTTP URL `https://mcp.coinset.org/`.

## Choosing a network

One connection reaches both chains. Every chain-querying tool takes an optional `network`:

* `network: "mainnet"` (the default) or `network: "testnet11"`.
* If you pass a `txch1…` / `xch1…` address, the network is **inferred** from its prefix.
* Passing a `network` that conflicts with an address prefix returns a `network_mismatch` error.

## Tools

**Chain & blocks** — `get_chain_state`, `get_block`, `get_block_changes`, `list_reorgs`

**Coins** — `find_coins`, `compute_coin_id`

**Wallet / address** — `get_address_balance`, `list_address_assets`, `get_clawback_coins`

**Transactions** — `get_transaction`, `list_transactions`, `wait_for_confirmation`

**Assets** — `get_asset_info`, `get_asset_coins`

**Offers** — `get_offer`, `list_offers`, `decode_offer`

**Mempool & fees** — `mempool`, `estimate_fee`

**Pricing** — `get_price`

**Utilities** — `search`, `convert_address`

**Inspection & CLVM** — `inspect`, `clvm`

Conventions:

* Addresses (`xch1…` / `txch1…`) and `0x`-hex puzzle hashes are interchangeable inputs.
* Amounts are in **mojos** (1 XCH = 1,000,000,000,000 mojos; 1 CAT = 1,000 mojos).
* List tools accept `limit`, `cursor`, and `order`.
* `list_transactions` (by `address`) merges pending mempool transactions when `include_pending` is
  true, tagging each result with its `status`.

For the exact request/response schemas behind these tools, see the **[API reference](/docs/api)**.

## Prompts

Pre-built prompts your client can invoke directly:

* `network_status` — current chain state and XCH price
* `address_summary` — balances, assets, recent activity, USD value
* `transaction_summary` — transfers, swaps, and fee for a transaction
* `offer_summary` — what an offer gives vs. receives
* `block_summary` — block details and notable coins

## Resources

Read-only reference material the agent can pull in:

* `coinset://guide/operating-rules`
* `coinset://reference/puzzle-mod-hashes`
* `coinset://reference/conditions`
* `coinset://reference/openapi`

## Example prompts

> What's the current Chia chain state — peak height and mempool size?

> What's the XCH balance of `xch1…`? Convert it to USD.

> Decode this offer and tell me what I give vs. get: `offer1…`

> Compare the mainnet and testnet11 peak heights right now.

> What kind of coin is `0x…`? Pull its puzzle and parsed conditions.

## What it isn't

* A wallet. No private keys, no signing, no `push_tx` / `push_offer`.
* A full node. It queries Coinset's indexed view of the chain.
* A realtime stream. It serves snapshot data (use polling or Coinset
  **[webhooks](/docs/webhooks)** for live events).