Aries — AI companion for building on Alkanes + Subfrost

What Aries is

An MCP server that makes your AI fluent in Alkanes.

Aries is a local Model Context Protocol server. Point any MCP-capable assistant — Claude Code, Claude Desktop, or a compatible tool — at it and it becomes a fluent builder for Alkanes (the Bitcoin metaprotocol for smart contracts and tokens) and Subfrost (its application + AMM layer).

⌕

Searchable knowledge

A bundled corpus of Alkanes + Subfrost protocol docs, API/JSON-RPC reference, the alkanes-rs CLI, oracle patterns, and 21 step-by-step tutorials — searched and read token-efficiently.

⛓

Live chain data

Read-only queries against the Subfrost gateway: token & contract metadata, balances by address, AMM pools, oracle prices, frBTC peg + signer status, and a raw RPC escape hatch.

⚒

Dev scaffolds

Key constants and starter recipes for wrapping/unwrapping frBTC, an alkanes-rs WASM contract skeleton, and Orbital (NFT) templates — starting points, not audited code.

↺

Learning loop

Record mistakes and pitfalls locally, then query them before non-trivial work so future sessions don't repeat them. Secrets, keys and paths are auto-sanitized.

Read-only by design. Aries v1 does no signing, broadcasting, or key management — chain-data tools are query-only and the aries_rpc passthrough blocks every write/broadcast method. Actual deployment stays in the alkanes CLI, where you hold your keys.

Install & connect

Build it, then add it to your MCP client.

Aries runs locally over stdio. Build the server once, then register it with your client.

1 · Build the server

# in the aries-mcp repo
npm install
cp .env.example .env        # add your SUBFROST_API_KEY
npm run build
npm run ingest              # optional: pull fuller docs into corpus/ (needs network)

2a · Claude Code (stdio)

claude mcp add --scope local --transport stdio aries \
  -e SUBFROST_API_KEY=YOUR_KEY \
  -- node /absolute/path/to/aries-mcp/dist/index.js

Put the server name before the -e flags, and keep -e … right before --. Verify with claude mcp list, then /mcp in a session.

2b · Claude Desktop (JSON)

{
  "mcpServers": {
    "aries": {
      "command": "node",
      "args": ["/absolute/path/to/aries-mcp/dist/index.js"],
      "env": { "SUBFROST_API_KEY": "..." }
    }
  }
}

The API key is sent as the x-subfrost-api-key header. Get one at api.subfrost.io. SUBFROST_RPC/SUBFROST_REST override the gateway (mainnet by default; set for regtest/signet).

Capabilities

21 tools, four layers.

Every tool is read-only or local. Names match what your assistant calls.

Knowledge 5 tools · search & read the corpus

aries_searchSearch the Alkanes + Subfrost docs corpus (protocol, API/JSON-RPC, alkanes-rs CLI, tutorials, oracles, reference). Returns path, heading, preview.

aries_docRead a corpus doc token-efficiently — table of contents without a section, the body of one section with it.

aries_full_docReturn the complete, untruncated markdown of a corpus doc by path.

aries_catalogList every doc in the corpus, grouped by source (subfrost, subfrost-api, alkanes-rs, tutorials, oracles, orddao, reference).

aries_tutorialsList the step-by-step Alkanes/Subfrost tutorials (title, summary, read-time, doc path) — contracts, tokens, DAOs, oracles, stablecoins, AMMs, frBTC/DIESEL, indexers, security.

Chain data 12 tools · live, read-only via the Subfrost gateway

aries_tokens_by_addressList all Alkanes tokens held by a Bitcoin address — outpoints and rune balances.

aries_contract_metaGet an Alkanes contract's metadata (name, symbol, decimals, totalSupply) by alkane id, via the meta view.

aries_tokenRead any Alkanes token's metadata via opcode views — works even when the meta view does not (detects frBTC- or orbital-style supply).

aries_bytecodeFetch the raw WASM bytecode (hex) of an Alkanes contract — pair with the alkanes CLI for disassembly.

aries_simulateSimulate Alkanes view calls (read-only contract state) without broadcasting; opcode goes in the inputs array.

aries_frbtc_statusfrBTC (32:0) name, symbol, decimals, total supply and current signer in one call — is the peg live, who's the signer, how much exists?

aries_diesel_statusDIESEL (genesis 2:0, the base pairing token for AMMs) — name, symbol, decimals, totalSupply in one call.

aries_oracle_readRead a value from a deployed Alkanes oracle via a staticcall-safe view; decode as hex, u128/u64/u32, utf8, bool, or price.

aries_oracle_priceRead the latest price from a Chainlink-style price-feed oracle (GetPrice) — priceE8, price, price/updated block, age.

aries_poolsList Alkanes AMM liquidity pools for a factory — reserves, TVL, 24h volume, trending — via the Subfrost REST API.

aries_pool_infoDetails for a single Alkanes AMM pool: reserves, token pair, price.

aries_rpcEscape hatch: call any read-only Subfrost gateway method directly (esplora_*, ord_*, metashrew_*, alkanes_*, brc20_*). Write/broadcast methods are blocked.

Dev 2 tools · constants & scaffolds

aries_constantsKey Alkanes/frBTC constants instantly: frBTC id, wrap/unwrap/get-signer opcodes, genesis block, protocol tag.

aries_scaffoldStarter recipes for wrap/unwrap frBTC protostones, an alkanes-rs WASM contract skeleton, and an Orbital NFT — templates, not audited code.

Learning 2 tools · a local memory of mistakes

aries_incident_reportRecord a bug, rule violation, or pitfall for future sessions. Stored locally; secrets, keys and paths are auto-sanitized.

aries_incident_queryQuery past incidents — recent, search, stats, or by id — before non-trivial work, so known mistakes aren't repeated.