Raxol MCP server
Commit Nov 15, 2026Builds Elixir/OTP terminal, browser, and SSH apps whose UI components automatically expose MCP tools to AI agents.
Also known as DROOdotFOO/raxol
- Stars
- 81
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 2.6.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is Raxol MCP?
Raxol builds Elixir/OTP terminal, browser, and SSH apps whose UI components automatically expose MCP tools to AI agents.
Summary generated from the project's README
About Raxol MCP server
Building Elixir and OTP applications that function across multiple interfaces is the core purpose of Raxol. Developers can write a single TEA module as an OTP GenServer and render it simultaneously to a terminal, a web browser via Phoenix LiveView, an SSH session, or an AI agent. This approach allows a single codebase to serve both human users and automated agents without needing to scrape pixels or interpret visual layouts.
When used with AI clients like Claude Code, the server provides tools derived directly from the application's component tree. For example, a Button component automatically provides a click tool, while a TextInput provides tools to type or clear values. The system runs locally via stdio using the command mix mcp.server. It is designed for high-reliability environments, offering crash isolation per component and hot code reloading through the BEAM runtime. This makes it suitable for developers building complex, distributed systems that require persistent state and real-time responsiveness.
What you can do with it
- 1Expose UI components to agentsAn AI agent can interact with application elements like buttons and text inputs through automatically generated MCP tools.
- 2Integrate with Claude CodeDevelopers can connect their Elixir applications to Claude Code by starting the MCP server on stdio.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
MIX_ENVSKIP_TERMBOX2_TESTS
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledroodotfoo/raxol is public and reachablegithub.com/droodotfoo/raxol ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/droodotfoo/raxol ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRaxol
Recursively, axol. Forever FOSS.
Write one app. Render it to a terminal, a browser, an SSH session, or an agent.
Your application is a single TEA module (init, update, view) running as an OTP GenServer. Raxol renders that module to four surfaces from one codebase:
+---> Terminal (termbox2 NIF)
|
TEA module (GenServer) -+---> Browser (Phoenix LiveView)
|
+---> SSH (Erlang :ssh)
|
+---> Agent (MCP tools)
The interesting part is the runtime. Your app gets crash isolation per Component, hot code reload without restart, distributed clustering with CRDTs, and an agent surface where LLMs interact with structured Component trees instead of scraping pixels. Those are BEAM properties, from a VM built for systems that can't go down, can't lose state, and hot-swap code while running.
Bubble Tea, Ratatui, and Textual are excellent renderers. A2UI and AG-UI define agent-UI wire formats. Raxol is the runtime that renders all four surfaces from one source module. See Why OTP for the framework comparison, and Why Raxol for how the runtime compares to Python agent stacks like Hermes and Omnigent.
Agents
Raxol is a runtime for agents as much as for humans. Every interactive Component automatically exposes MCP tools (Button gives click, TextInput gives type_into/clear/get_value), and a focus lens filters to roughly 15 relevant tools per interaction. Where A2UI and AG-UI define how agents talk to UIs at the wire level, raxol generates the UI and the agent surface from one Component tree: same source, two projections.
import Raxol.MCP.Test
import Raxol.MCP.Test.Assertions
session = start_session(MyApp)
session
|> type_into("search", "elixir")
|> click("submit")
|> assert_component("results", fn c -> c[:content] != nil end)
|> stop_session()
mix mcp.server starts the MCP server on stdio for Claude Code integration, and mix raxol.code is an interactive terminal coding agent (the axol face) with every mutating tool call gated by an ALLOW/ASK/DENY authorization engine. See the Coding Agent.
Code is the coding-agent product, in two hands-on surfaces: mix raxol.code is the interactive terminal TUI (the axol face ≡··≡), and mix raxol.p is its headless twin (prompt in on argv, answer to stdout, contract events to stderr) for pipes and CI. Every mutating tool call is gated by an ALLOW/ASK/DENY authorization engine. From a clone, one setup command and one launch:
(cd packages/raxol_agent && mix deps.get) # once
bin/raxol-code # the TUI, your cwd as the workspace
No API key configured? The TUI opens on a provider wizard instead of failing. /inspect (or mix raxol.inspect from packages/raxol_agent) shows every config source the agent will use in the current directory.
Sessions are durable. Each session journals its events to disk, so --continue and --resume <id> restore the model context and the scrollback together, --replay <id> prints a transcript straight from the journal (--to-offset N stops at an offset), /rewind drops back to an earlier turn, and /share mints a signed 24-hour link to a read-only transcript that follows the session live (needs RAXOL_SHARE_SECRET and a host mounting Raxol.Agent.Code.ShareLive).
The same TUI serves over SSH: mix raxol.code --ssh --ssh-tenants /srv/tenants hosts many users from one daemon, each behind their own public key with their own cwd jail, session store, and spending identity (ssh <you>@your-host -p 2222 is the whole client). Single-tenant (--authorized-keys) and hosted deployment (RAXOL_SSH_CODE=true) are in Coding Agent.
Two unattended surfaces run the same agent. bin/raxol-acp (or mix raxol.acp) serves it over the Agent Client Protocol on stdio, for editors that spawn an agent themselves; Raxol.Agent.Harness.McpTools registers harness_start_session, harness_send_prompt, harness_read_transcript, and harness_list_sessions with the MCP registry, so a session started by an MCP client resumes later in the TUI. The ACP surface runs the full toolset with every sensitive call gated on a session/request_permission round trip, fail-closed on the decision: a client that refuses, times out, or does not implement permissions denies the write and keeps reading. The MCP surface stays read-only: write_file, edit_file, and bash are absent where nobody is there to answer an approval prompt.
Every one of those surfaces sits on the Harness, the agent-session engine: a durable event journal (Raxol.Agent.Journal), a typed event/command contract (Raxol.Agent.Contract), and surface state that is a pure fold over the event stream (Raxol.Harness.Projection), with staged interrupt, steer, and spend/blast-radius gates underneath. The same engine can supervise external agent CLIs (claude, cursor) as readily as Raxol's own loop. See Harness architecture.
The agent subsystems ship as standalone packages:
- Pay (
raxol_payments): wallets, ledger-enforced spending limits, and transparent auto-pay when an agent hits an HTTP 402, across five protocols (x402, MPP, Xochi cross-chain, Permit2, Riddler). - Earn (
raxol_earn): the sell side. Declare an offering, implement two callbacks, and a buyer agent discovers it, escrows funds, and settles on-chain through the Virtuals ACP job lifecycle (request, negotiation, transaction, evaluation, completed), one supervised process per job. Pre-alpha. - Improve (
raxol_agent): a solved task becomes a reusableSKILL.md. A background reviewer runs on a cheap model after each turn, writing durable memory and new skills without spending the live turn's latency or context. - Reach (
raxol_gateway): one adapter contract to many chat platforms, process-per-chat sessions, DM pairing for authorization, and/handoffto move a conversation across platforms with its history intact. - Bridge (
raxol_agent_client_protocol): Elixir/OTP implementation of the Agent Client Protocol: the JSON-RPC 2.0 wire protocol between code editors and AI coding agents (the protocol Zed and a growing ecosystem speak). Bidirectional agent/client roles, pluggable transports (stdio, in-process), and durable resumable sessions (offset-based reattach/replay) as a vendor extension. Zero raxol-internal deps. Pre-alpha.
Install
# mix.exs
def deps do
[{:raxol, "~> 2.7"}]
end
Or generate a new project:
mix raxol.new my_app
With Nix, nix develop drops you into a shell with the full BEAM and NIF toolchain (no local Elixir install required):
nix develop github:DROOdotFOO/raxol # dev shell with elixir, erlang, NIF + speech deps
Try it
Nothing to install: raxol.io runs the same catalog in a
browser, one LiveView per demo. That surface is this repo's web/ app; see
web/README.md to run it yourself. In a terminal:
git clone https://github.com/DROOdotFOO/raxol.git
cd raxol && mix deps.get
mix raxol.playground # 42 live demos, browse/search/filter
The flagship demo is a live BEAM dashboard with scheduler utilization, memory sparklines, and a process table:
mix run examples/demo.exs
See examples/README.md for the full learning path, including agent examples, swarm demos, and the REPL.
Headless environment (CI, containers, agents)? The whole build-and-test path needs no tty:
mix local.hex --force # fresh machines and CI: install Hex without a prompt
mix deps.get
mix compile # termbox2 NIF needs make + a C compiler
SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker
MIX_ENV=test mix raxol.rate # RATE: render-determinism golden suite
Prerequisites, the quality gate, and constrained-sandbox notes are in Development.
Performance
Full frame in 5.0ms on Apple M1 (Elixir 1.20 / OTP 29), 31% of the 60fps budget.
| What | Time |
|---|---|
| Full frame (create + fill + diff) | 5.0 ms |
| Tree diff (100 nodes, 1 changed) | 32 us |
| Cell write (single) | 1.4 us |
| Buffer create (80x24) | 0.32 us |
| Emulator ingest (parse + apply, plain) | 1.7 ms |
| Memory per 80x24 buffer | 2 KB |
Measured 2026-08-07 at fce2465bb with mix run bench/suites/comparison/framework_comparison.exs (full mode). The ingest row is the whole emulator path (parse plus state application), not the standalone ANSI lexer, which handles plain text in under a microsecond (mix raxol.bench parser).
Unix/macOS backend uses a termbox2 NIF; Windows uses a pure Elixir driver (usable, not yet tuned). See the benchmark suite.
Documentation
Start with the documentation index, or jump to:
Development
Working from source needs Elixir/OTP (versions in mise.toml) and a C
toolchain: the termbox2 NIF compiles with make and cc (on Debian/Ubuntu,
apt-get install build-essential). nix develop provides all of it in one
shell. Every command below runs headless: no terminal is required for the
build, the test suite, or the golden checks.
git clone https://github.com/DROOdotFOO/raxol.git
cd raxol
mix local.hex --force # fresh machines and CI: install Hex without a prompt
mix deps.get
mix compile # builds the termbox2 NIF
SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker
MIX_ENV=test mix raxol.rate # RATE: render-determinism golden suite
mix raxol.check # full gate: format, compile, credo, dialyzer, security, docs, rate, test
mix raxol.check --quick # skip dialyzer
mix raxol.demo # built-in demos (needs a terminal)
SKIP_TERMBOX2_TESTS=true excludes the tests that need a real local terminal
(pty lifecycle, timing-sensitive suites); CI sets the same variable. Plain
mix test without the exclude flags also runs integration suites that need
external services (the workflow checkpoint tests want PostgreSQL via
RAXOL_WORKFLOW_PG_URL), so stick to the command above unless you have
them. In sandboxes where HOME is read-only, point MIX_HOME and
HEX_HOME at a writable directory before running mix.
Origin
Raxol started as two converging ideas: a terminal for AGI, where AI agents interact with a real terminal emulator the same way humans do; and an interface for the cockpit of a Gundam Wing Suit, where fault isolation, real-time responsiveness, and sensor fusion are survival-critical. The Gundam thing sounds like a joke. Then you look at the constraint set and it's exactly what OTP was built for: systems that can't go down, can't lose state, and have to hot-swap components while running.
The longer vision is Raxol: The Terminal For My Gundam.
Built with Raxol
Xochi is a private cross-chain DEX (intent-based swaps across 6 chains, sub-3s settlement, stealth addresses by default, ZKSAR compliance proofs) whose entire trading surface is raxol. One Component tree projects four ways: an SSH trader terminal, a LiveView web UI, a solver-agent surface for Riddler's sub-2ms solver, and an ops cockpit running sensor fusion on solver health. The solver executes behind a dedicated fail-closed stack (buyer-pre-signed intents, ledger-enforced spend gates, deployment guards that refuse to run unconfigured), kept deliberately off the MCP surface, so no fund-moving action is reachable as a generic tool call.
foglet-bbs by Brendan Turner is an SSH-only retro bulletin board (bbs.foglet.io, ssh bbs.foglet.io) that stress-tested raxol's SSH path into shape.
License
MIT. See LICENSE.md.
Raxol MCP questions
How do I start the Raxol MCP server?
Run mix mcp.server, which starts the MCP server on stdio for Claude Code integration.
What MCP tools does a Raxol component expose?
Each interactive component exposes its own tools, such as Button giving click and TextInput giving type_into, clear, and get_value.
Does Raxol limit how many tools an agent sees at once?
Yes, a focus lens filters the tool set to roughly 15 relevant tools per interaction.
What surfaces can a Raxol app render to?
One TEA module renders to a terminal, a browser via Phoenix LiveView, an SSH session, and an agent through MCP tools.
Is authentication needed to use the Raxol MCP server?
The stdio MCP server is started locally with a mix task and no credentials are described for it; the coding agent instead uses an ALLOW/ASK/DENY authorization engine.