# THORChain Swap MCP Server

THORChain Swap runs a public [Model Context Protocol](https://modelcontextprotocol.io) server so AI agents can read live THORChain data natively.

- **Endpoint:** https://swap.thorchain.ai/mcp
- **Transport:** Streamable HTTP (stateless — single JSON responses, no SSE stream, no sessions)
- **Protocol versions:** 2025-06-18, 2025-03-26, 2024-11-05
- **Manifest:** [https://swap.thorchain.ai/.well-known/mcp/server-card.json](https://swap.thorchain.ai/.well-known/mcp/server-card.json) (also served by `GET https://swap.thorchain.ai/mcp`)
- **Authentication:** none — no key, no token, no OAuth

## Add it to a client

Claude Code:

```bash
claude mcp add --transport http thorchain-swap https://swap.thorchain.ai/mcp
```

VS Code:

```bash
code --add-mcp '{"name":"thorchain-swap","type":"http","url":"https://swap.thorchain.ai/mcp"}'
```

Claude Desktop, Cursor, and anything else that reads an `mcpServers` config:

```json
{
  "mcpServers": {
    "thorchain-swap": {
      "type": "http",
      "url": "https://swap.thorchain.ai/mcp"
    }
  }
}
```

No credential goes in any of these, and none is needed: if a connector UI asks for an OAuth client ID or an API key, leave it blank. See [authentication](https://swap.thorchain.ai/developers/auth).

## Tools

### `get_swap_quote` — Get Swap Quote

Fetch a THORChain swap quote for an asset pair. Assets use CHAIN.SYMBOL notation (e.g. BTC.BTC, ETH.ETH, ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48). Amount is in 1e8 base units (1 BTC = 100000000). Quotes are indicative and expire quickly; the returned memo and inbound address must not be reused after expiry.

Parameters:

  - `from_asset` (string, required) — Source asset, e.g. BTC.BTC
  - `to_asset` (string, required) — Destination asset, e.g. ETH.ETH
  - `amount` (string, required) — Amount to swap in 1e8 base units
  - `destination` (string) — Optional destination address; required for a quote with a usable memo
  - `streaming_interval` (string) — Optional streaming swap interval in blocks

### `list_pools` — List Liquidity Pools

List THORChain liquidity pools with status, depths (1e8 base units), and USD asset price. Filter by pool status or by chain/asset to avoid pulling the full list.

Parameters:

  - `status` (string) — Only return pools in this state. Available pools are the tradable ones.
  - `asset` (string) — Case-insensitive filter on the pool asset. A bare chain returns that chain only (ETH matches every ETH.* pool, not BASE.ETH); a CHAIN.SYMBOL value matches by prefix, so BTC.BTC returns one pool and ETH.USDC finds the contract-suffixed pool.
  - `limit` (integer) — Maximum number of pools to return, largest RUNE depth first. Omit to return every match.

### `get_network_status` — Get Network Status

Return current THORChain network parameters, including outbound fees, bond and reserve totals, and halt-related gas information. Pass `fields` to return only the keys you need.

Parameters:

  - `fields` (array) — Subset of top-level keys to return, e.g. ["native_outbound_fee_rune", "outbound_fee_multiplier"]. Omit for the full object.

Every tool is annotated `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`. The server holds no keys, signs nothing, and submits no transactions.

## Example

```bash
curl -s https://swap.thorchain.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_swap_quote",
      "arguments": {
        "from_asset": "BTC.BTC",
        "to_asset": "ETH.ETH",
        "amount": "100000000"
      }
    }
  }'
```

List the tools and their JSON Schemas:

```bash
curl -s https://swap.thorchain.ai/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## MCP Apps

The server implements the MCP Apps extension (`io.modelcontextprotocol/ui`): `get_swap_quote` declares `_meta.ui.resourceUri` pointing at `ui://thorchain-swap/swap-quote`, a self-contained `text/html;profile=mcp-app` resource that MCP Apps-capable hosts render as an interactive quote panel. Hosts without MCP Apps support receive plain JSON and `structuredContent`.

## Transport notes

The server is stateless: no session id, no SSE stream, one JSON response per POST. A `GET` asking for `text/event-stream` returns 405; any other `GET` returns the server card. JSON-RPC batches are accepted for clients that negotiate a protocol revision allowing them — send an array, get an array back, with notifications answered by an empty `202`.

## Rate limits

60 requests per 10 minutes per client IP. Exceeding that returns JSON-RPC error `-32000` with HTTP 429 and a `Retry-After` header.

## Related

- [Quickstart](https://swap.thorchain.ai/developers/quickstart)
- [Authentication](https://swap.thorchain.ai/developers/auth)
- [SDKs](https://swap.thorchain.ai/developers/sdks)
- [AGENTS.md](https://swap.thorchain.ai/AGENTS.md)