Olex

Overview

Olex speaks the Model Context Protocol over stdio. Your client launches it as a child process and talks JSON-RPC over stdin and stdout, so there is no port to open and no service to host.

Ask your assistant "what's the latest Aleo block height?" or "does credits.aleo leak the transfer amount?" and it calls the tools below directly instead of you switching to a terminal.

• Read-only by default. The chain tools hold no keys and sign nothing, so an agent cannot move funds with them.
• Privacy analysis needs no keys at all. It is static analysis of deployed Aleo instructions.
• View-key tools run over stdio only. They are never registered on the hosted surface, so the bridge has no code path that could accept a view key. See Surfaces. Two of the three are pure local computation and reach no network at all; olex_true_balance is the exception, since it must read the chain before it can decrypt anything.

Install

1. Build

   git clone https://github.com/Ritapossible/Olex.git
   cd olex
   npm install
   npm run build

2. Register with your client

   Claude Code and Codex can write their own config. Everything else is a file you edit by hand.

   claude mcp add olex -- node /abs/path/olex/dist/index.js   # Claude Code
   codex mcp add olex -- node /abs/path/olex/dist/index.js    # Codex CLI

   For the rest, find your client below, then paste the matching block from config shapes. The key column is the part people get wrong - a correct-looking block under the wrong key fails silently, with the server simply absent from the tool list.

   Client	Config file	Key
   Claude Code	claude mcp add, or .mcp.json in the project	mcpServers
   Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows	mcpServers
   Cursor	~/.cursor/mcp.json globally, .cursor/mcp.json per project	mcpServers
   VS Code	.vscode/mcp.json, or MCP: Open User Configuration	servers
   Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers
   Codex CLI	~/.codex/config.toml	mcp_servers (TOML)
   Gemini CLI	~/.gemini/settings.json	mcpServers
   Zed	settings.json, via zed: open settings	context_servers
   Cline / Roo Code	cline_mcp_settings.json / mcp_settings.json	mcpServers

3. Ask

   "What's the latest Aleo block height?"
   "Audit the privacy of credits.aleo."
   "What did transaction at1fv877... reveal publicly?"

The path must be absolute. A client launches the server from its own working directory, not yours. On Windows, either escape the separators (C:\\path\\to\\olex\\dist\\index.js) or use forward slashes - Node accepts both, but a single backslash in JSON is an escape character and will not survive parsing.

Config shapes

Three shapes cover every client. They are not interchangeable: the block is identical, the key around it is not.

Most clients

Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Cline and anything else that follows the reference format.

{
  "mcpServers": {
    "olex": {
      "command": "node",
      "args": ["/abs/path/olex/dist/index.js"],
      "env": { "OLEX_NETWORK": "testnet" }
    }
  }
}

VS Code

The top-level key is servers, and each entry carries an explicit type.

{
  "servers": {
    "olex": {
      "type": "stdio",
      "command": "node",
      "args": ["/abs/path/olex/dist/index.js"],
      "env": { "OLEX_NETWORK": "testnet" }
    }
  }
}

Zed

Zed calls them context servers and speaks stdio only, which suits Olex exactly.

{
  "context_servers": {
    "olex": {
      "command": "node",
      "args": ["/abs/path/olex/dist/index.js"],
      "env": { "OLEX_NETWORK": "testnet" }
    }
  }
}

Codex CLI

TOML rather than JSON, and the key is snake_case.

[mcp_servers.olex]
command = "node"
args = ["/abs/path/olex/dist/index.js"]
env = { OLEX_NETWORK = "testnet" }

Whichever client you use, restart it after editing the file. Most read their MCP config only at startup, and Windsurf needs a full quit rather than just a closed window.

Configuration

Every setting is an environment variable, and every one has a working default.

Testnet is the default everywhere. Pointing an autonomous agent at mainnet should be a deliberate act, not something it drifts into.

Privacy model

Aleo splits state in two, and the split is the thing worth understanding before reading the tool list:

• Public state lives in mappings. Anyone can read it. This is what a block explorer shows.
• Private state lives in encrypted records. Only the account's view key can read them.

Tool reference

Ten tools need no key material and run on every surface, hosted included. Arguments in italics are optional. Every tool also accepts network.

Chain

Privacy analysis

Utility

View-key tools

Three tools read your private records. They exist only in the local stdio server, and they are the one thing no block explorer can do for you.

olex_true_balance needs a scope: either a transaction_id or a from_block/to_block range of at most 50 blocks. It refuses an unbounded scan rather than quietly walking the chain, and the private figure it reports covers only the range actually scanned.

Prompts

Prompts appear in an MCP client as slash commands. A tool list asks you to know which tool to reach for; a prompt states an intent and lets the model plan the calls.

Surfaces

Olex runs on two surfaces, and they do not expose the same tools. The difference is structural rather than a filter.

The hosted bridge imports the shared server factory, which never imports the view-key module. So those tools cannot be constructed there even by mistake, tools/list over HTTP cannot advertise one, and the WASM cryptography they need never enters the serverless bundle. A separate allow-list in the bridge is a second, independent barrier rather than the only one.

The playground runs against that hosted bridge. It opens a genuine MCP session server-side and dispatches a real tools/call, so the code it exercises is the same code your editor gets over stdio - not a browser reimplementation.

Verify

npm run smoke      # drives the real server over stdio against live testnet
npm run inspect    # opens the official MCP Inspector web UI

npm run smoke spawns the built binary the way a client would and hits the live network. It is deliberately not a unit test with mocks: the point is to prove the whole path works, not that the pieces work in isolation.

npm run inspect prints a localhost URL with an auth token, which is the closest thing to a live URL an MCP server has. MCP servers speak JSON-RPC over stdin and stdout; they are launched by the client, not hosted on a port.