Aries

Make any AI assistant fluent in building on Alkanes + Subfrost

Use the hosted Aries API  ·  bragi.build/aries

Aries is a Model Context Protocol server that gives any MCP-capable assistant — Claude Code, Claude Desktop, Cursor — a knowledge and live-chain-data layer for the Alkanes metaprotocol and the Subfrost network. Point your assistant at Aries and it can read the protocol docs, query the live chain, and scaffold contracts without leaving the editor.

There are two ways to use it: the hosted API (recommended) and a bring-your-own-key local install.

The hosted API — the living Aries

Subscribe to hosted Aries  ·  bragi.build/aries

The hosted edition is live now and it is the way to get the full Aries. It is a continuously-learning instance: on top of the baseline docs it carries an ever-growing corpus of real-world lessons — reviewed incident knowledge contributed by every connected agent — that a fresh local clone does not have. Connect one URL and your assistant inherits the whole shared brain, which gets smarter every day.

Prefer to run everything yourself? The open, bring-your-own-key edition in this repo is below.

Related MCP server: midnight-mcp

Hosted vs. local

Both editions ship the same 21 tools and the same 75-doc baseline. The difference is the living corpus — and who manages the keys.

Local gives you a complete, self-contained companion on the static baseline. Hosted adds the continuously-learning brain on top. Start local if you like; move to hosted when you want the living corpus.

Run it locally (bring your own key)

Clone this repo and run Aries on your own machine with your own Subfrost API key. You get the full toolset and the complete 75-doc static baseline knowledge — without the hosted instance's accumulated learning.

Get a Subfrost API key

Aries talks to the Subfrost gateway with your key.

Sign up for a Subfrost API key — sign up with our Subfrost referral link and get 50% off your first month.

Quickstart

Requirements: Node.js >= 20 and a Subfrost API key (sign up with our referral link for 50% off your first month).

git clone https://github.com/bitbragi/alkanes-aries.git
cd alkanes-aries
npm install
cp .env.example .env        # then set SUBFROST_API_KEY (see below)
npm run build

Set your key in .env:

SUBFROST_API_KEY=your-key-here
# optional override:
# SUBFROST_RPC=https://mainnet.subfrost.io/v4/jsonrpc

The key is sent as the x-subfrost-api-key header (never in a URL) and never leaves your machine except as that outbound header. .env is gitignored.

Connect your MCP client

Claude Code

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

Verify with claude mcp list, then /mcp in a session. (-- separates Claude's flags from the launch command; keep -e KEY=value right before -- — it is variadic and will otherwise swallow the server name.)

Cursor / Claude Desktop — any client that takes a JSON server config:

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

Your assistant now has all 21 Aries tools.

What's inside — 21 tools, four layers

Ask your assistant things like

"Is the frBTC peg live, who's the signer, and how much frBTC exists?"

"What Alkanes tokens does bc1p… hold?"

"Show the AMM pools and a pool's reserves."

"How do I build a token / oracle / stablecoin / AMM / Orbital?"

"Scaffold an Orbital NFT contract."

Safety — read-only by design

Aries is analytics only. It never signs, broadcasts, or touches wallets or keys:

• The aries_rpc passthrough is allowlisted to read methods and explicitly blocks broadcast / spend / admin calls.

• Scaffolds and constants are emitted for you to run in your own alkanes CLI, where you hold the keys.

• The local incident loop writes only to your machine and sanitizes secrets, keys, and paths out of any report.

Your keys stay yours. Aries only reads and advises.

Configuration

Logs go to stderr only — stdout is the MCP protocol channel. The doc index is built from corpus/ at startup.

Good to know

• Alkane ids are {block, tx} / block:tx. frBTC = 32:0, DIESEL (genesis) = 2:0. Protocol tag is always 1.

• Read contract state with aries_simulate: the opcode goes in inputs (e.g. [103]), not data.

• Orbitals (Alkanes NFTs) are a Token with total supply 1 + opcode 1000 for media; read them with aries_oracle_read, scaffold one with aries_scaffold orbital.

• Extend the corpus by editing corpus/ or adding URLs to scripts/ingest.ts (HTML cleaned via turndown + jsdom; raw .md/.rs taken verbatim).

Links

License

MIT