THORChain MCP Server
A production-grade MCP (Model Context Protocol) server that provides unified, tool-based access to THORChain data via Midgard and THORNode REST APIs.
Features
- 127 MCP Tools for querying THORChain data (16-tool swap set by default; the full set via
THORCHAIN_TOOLSET=full, and over HTTP always at /mcp/full)
- Intelligent Source Selection with automatic fallback
- In-Memory Caching with TTL support
- Resilience Patterns: Retry with exponential backoff, circuit breaker
- Rate Limiting: Per-client rate limiting for HTTP transport
- Dual Transport: stdio (default) and HTTP modes
- MCP 2026-07-28 (stateless): HTTP serves the current stateless protocol
revision; legacy clients (2025-06-18/2025-11-25) are auto-negotiated
per-request (dual-era). No protocol sessions, no
Mcp-Session-Id.
- Structured Logging for observability
- Multi-Network Support (mainnet, stagenet, testnet)
Hosted endpoint
The server is hosted at https://mcp.thorchain.org/mcp (Streamable HTTP,
no authentication, mainnet). Point any MCP client at it; nothing to install.
https://mcp.thorchain.org/mcp: the 16-tool swap set (price, prepare and
track a swap, plus pools and network status). Agents pick tools more
reliably from a small set, so start here.
https://mcp.thorchain.org/mcp/full: all 127 tools (nodes, vaults, mimir,
Midgard history, CometBFT, Cosmos and the rest). Same transport, no auth.
| Client | How to connect |
|---|
| Claude (claude.ai, Claude Desktop) | Settings, Connectors, Add custom connector, URL https://mcp.thorchain.org/mcp |
| Claude Code | claude mcp add --transport http thorchain https://mcp.thorchain.org/mcp |
| Cursor | .cursor/mcp.json: {"mcpServers":{"thorchain":{"url":"https://mcp.thorchain.org/mcp"}}} |
| VS Code | .vscode/mcp.json: {"servers":{"thorchain":{"type":"http","url":"https://mcp.thorchain.org/mcp"}}} |
| OpenClaw | config: {"mcp":{"servers":{"thorchain":{"url":"https://mcp.thorchain.org/mcp","transport":"streamable-http"}}}} |
| Grok | grok.com/connectors, New Connector, Custom, paste the URL |
| Any other client | Streamable HTTP transport, URL above, no auth |
Try it from a terminal:
npx -y @modelcontextprotocol/inspector --cli https://mcp.thorchain.org/mcp --transport http --method tools/list
Discovery documents:
- Server card:
https://mcp.thorchain.org/.well-known/mcp/server-card.json
(name, version, endpoint and the live tool list, no session needed)
- Tool reference: api/mcp/tools.json
- Health:
https://mcp.thorchain.org/health
A swap, end to end
The server never holds keys or moves funds. It returns everything a wallet
needs; the user or their agent signs.
- Price it:
quote_swap with from_asset, to_asset, amount (base
units, 1e8). Returns expected output, fees, slippage and the inbound vault
address.
- Prepare it:
prepare_swap with the same fields plus destination
(and optional max_slippage_bps, affiliate, affiliate_bps). Returns
the vault address to send to, the exact memo, the guaranteed minimum
output and an expiry. Do not cache it; do not send after the expiry.
- Send: the wallet sends
send_amount to send_to with memo
attached, as a normal on-chain transfer on the source chain.
- Track:
get_swap_status with the deposit transaction hash. It
returns a plain status (pending, streaming, sent, refunded,
completed, or not_found), done, and a one-line summary to show the
user. Poll until done is true. get_tx_status has the raw THORNode
stages if you need them.
Example prepare_swap call, 0.1 BTC to ETH:
{"from_asset":"BTC.BTC","to_asset":"ETH.ETH","amount":10000000,"destination":"0xYourEthAddress"}
Earn on every swap (affiliate fees)
An app or agent that routes swaps can take a fee on each one. quote_swap,
prepare_swap and quote_limit accept:
affiliate: a THORChain address or a THORName that collects the fee.
affiliate_bps: the fee in basis points, 0 to 1000 (100 = 1%). THORChain
rejects a swap whose affiliate fees total more than 1000.
The fee comes out of the swap amount and is paid in RUNE by default. A
THORName with a preferred asset is paid in that asset instead, once its
collected RUNE passes a payout threshold. A fee too small to cover the
outbound cost is skipped. These tools take one affiliate per swap; several
affiliates are possible directly in a swap memo.
Example: 0.1 BTC to ETH with a 0.5% fee for the THORName myapp:
{"from_asset":"BTC.BTC","to_asset":"ETH.ETH","amount":10000000,"destination":"0xYourEthAddress","affiliate":"myapp","affiliate_bps":50}
Check what a THORName has earned with get_affiliate_earnings, and its payout
settings with get_thorname (both on /mcp/full). Registering a THORName and setting a preferred
asset is covered in THORNode's
affiliate fee guide
and THORName guide.
Installation
go install gitlab.com/thorchain/thorchain-mcp/cmd/thorchain-mcp@latest
Or build from source:
git clone https://gitlab.com/thorchain/thorchain-mcp.git
cd thorchain-mcp
go build -o thorchain-mcp ./cmd/thorchain-mcp
Usage
With Claude Desktop
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"thorchain": {
"command": "thorchain-mcp",
"env": {
"THORCHAIN_NETWORK": "mainnet"
}
}
}
}
Standalone
Run the MCP server directly (uses stdio transport):
| Tool | Description |
|---|
get_network_info | Returns network statistics and health information |
get_mimir | Returns protocol configuration parameters |
get_inbound_addresses | Returns vault addresses for deposits |
| Tool | Description |
|---|
list_pools | Returns all active liquidity pools |
get_pool | Returns details for a specific pool |
get_pool_stats | Returns analytics for a pool |
| Tool | Description |
|---|
get_swap_status | Plain swap status for a deposit hash: pending, streaming, sent, refunded or completed |
quote_swap | Get swap quote with expected output and fees |
prepare_swap | Build the deposit (vault address, memo, minimum out) for a swap |
get_tx | Returns transaction details |
| Tool | Description |
|---|
list_nodes | Returns all validator nodes |
get_node | Returns details for a specific node |
Configuration
All configuration is done via environment variables:
Core Settings
| Variable | Default | Description |
|---|
THORCHAIN_NETWORK | mainnet | Network to connect to (mainnet, stagenet, testnet) |
THORCHAIN_TOOLSET | core | Tools on the main endpoint: core = the 16-tool swap set, full = all 127 tools. Over HTTP all 127 are also always at /mcp/full |
THORCHAIN_MIDGARD_URL | Network default | Override Midgard endpoint |
THORCHAIN_THORNODE_URL | Network default | Override THORNode endpoint |
THORCHAIN_COMETBFT_URL | Network default | Override CometBFT RPC endpoint |
THORCHAIN_LOG_LEVEL | info | Log level (debug, info, warn, error) |
Cache Settings
| Variable | Default | Description |
|---|
THORCHAIN_CACHE_ENABLED | true | Enable/disable caching |
THORCHAIN_CACHE_MAX_SIZE | 1000 | Maximum cache entries (10-100,000) |
THORCHAIN_CACHE_POOLS_TTL | 30s | TTL for pool data |
THORCHAIN_CACHE_MIMIR_TTL | 60s | TTL for mimir data |
THORCHAIN_CACHE_NODES_TTL | 60s | TTL for node data |
THORCHAIN_CACHE_QUOTE_TTL | 5s | TTL for quote data |
Transport Settings
| Variable | Default | Description |
|---|
THORCHAIN_TRANSPORT | stdio | Transport mode (stdio, http) |
THORCHAIN_HTTP_HOST | localhost | HTTP server host |
THORCHAIN_HTTP_PORT | 8080 | HTTP server port (1-65535) |
THORCHAIN_PUBLIC_URL | (empty) | Public MCP URL advertised in the server card, e.g. https://mcp.thorchain.org/mcp. Empty derives it from each request's Host and X-Forwarded-Proto |
THORCHAIN_REGISTRY_AUTH_PROOF | (empty) | MCP registry HTTP ownership proof served at /.well-known/mcp-registry-auth; see docs/registry.md |
THORCHAIN_OPENAI_APPS_CHALLENGE | (empty) | OpenAI app-directory domain-verification token, served exactly at /.well-known/openai-apps-challenge |
Resilience Settings
| Variable | Default | Description |
|---|
THORCHAIN_TIMEOUT_REQUEST | 30s | Request timeout (1s-5m) |
THORCHAIN_RETRY_ENABLED | true | Enable retry logic |
THORCHAIN_RETRY_MAX_ATTEMPTS | 3 | Max retry attempts (1-10) |
THORCHAIN_RETRY_INITIAL_DELAY | 100ms | Initial retry delay |
THORCHAIN_RETRY_MAX_DELAY | 5s | Maximum retry delay |
THORCHAIN_CIRCUIT_BREAKER_ENABLED | true | Enable circuit breaker |
THORCHAIN_CIRCUIT_BREAKER_TIMEOUT | 30s | Circuit breaker reset timeout |
THORCHAIN_CIRCUIT_BREAKER_THRESHOLD | 5 | Failures to trip breaker (1-100) |
An upstream HTTP 429 (rate limited) is neither retried nor counted toward the
circuit breaker: retrying multiplies the load that caused it, and an open
breaker would fail every call instead of only the limited ones. The tool error
says it was rate limited, with the upstream's Retry-After when it is given in seconds.
The upstream URLs may carry an API key (Liquify, for example, takes it in the
path). Tool errors and logs never include the configured base URL's path,
query or credentials; startup logs show only scheme and host.
Rate Limiting (HTTP transport only)
| Variable | Default | Description |
|---|
THORCHAIN_RATE_LIMIT_ENABLED | true | Enable rate limiting |
THORCHAIN_RATE_LIMIT_RPS | 100 | Requests per second per client |
THORCHAIN_RATE_LIMIT_BURST | 200 | Maximum burst size |
x402 Payment Metering (HTTP transport only, off by default)
Premium tools can require an x402 USDC micropayment.
Verification and settlement are delegated to an external facilitator; this
server never touches keys or signatures. Testnet first: the default
facilitator and network are the keyless Base Sepolia setup.
| Variable | Default | Description |
|---|
THORCHAIN_X402_ENABLED | false | Enable payment metering |
THORCHAIN_X402_PAY_TO | (empty) | Receiving wallet address (required when enabled) |
THORCHAIN_X402_NETWORK | base-sepolia | base-sepolia or base |
THORCHAIN_X402_FACILITATOR | https://x402.org/facilitator | Facilitator base URL |
THORCHAIN_X402_PRICE_USDC | 0.01 | Dollars per premium call |
THORCHAIN_X402_PREMIUM_TOOLS | prepare_swap | Comma-separated tool names to meter |
Note: affiliate fees are capped at 1,000 bps (10%) total by the protocol; the
affiliate_bps inputs validate 0-1000.
Security Settings
| Variable | Default | Description |
|---|
THORCHAIN_MAX_RESPONSE_SIZE | 10485760 | Max response size in bytes (10MB) |
The SDK rejects requests that arrive on a loopback-bound listener with a
non-loopback Host header (DNS-rebinding protection, 403). If you front a
localhost-bound server with a proxy or tunnel, either bind a non-loopback
address or rewrite Host at the proxy.
Source Selection Policy
The server intelligently selects data sources based on the query type:
| Tool | Primary | Fallback | Canonical |
|---|
| list_pools | Midgard | THORNode | No |
| get_pool | THORNode | Midgard | Yes |
| get_pool_stats | Midgard | - | No |
| get_mimir | THORNode | - | Yes |
| get_inbound_addresses | THORNode | - | Yes |
| get_network_info | Midgard | THORNode | No |
| list_nodes | THORNode | - | Yes |
| get_node | THORNode | - | Yes |
| get_tx | THORNode | Midgard | Yes |
| quote_swap | THORNode | - | Yes |
All tool responses include metadata about the data source:
{
"_metadata": {
"source_used": "thornode",
"canonical": true,
"fetched_at": "2024-01-15T10:30:00Z",
"cache_hit": false
}
}
Architecture
┌──────────────────────────┐
│ MCP Layer │ ← stdio or HTTP transport
├──────────────────────────┤
│ Rate Limiting │ ← per-client throttling (HTTP only)
└────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ Core Tools │ ← tool handlers
└────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ Resolver Layer │ ← source selection & fallback
└────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ Transport Layer │ ← HTTP client, resilience patterns
├──────────────────────────┤
│ Retry + Breaker │ ← exponential backoff, circuit breaker
└────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ Data Sources │ ← THORNode, Midgard, CometBFT, Cosmos
└──────────────────────────┘
Development
Prerequisites
Build
Test
Run Integration Tests
go test -tags=integration ./...
License
MIT