MUTX Documentation

MUTX is a local authority layer for Solana wallets used by AI agents.

The public product has two parts:

• mutx-tui: the terminal UI that stores wallet state, shows approvals, and signs operations
• mutx-mcp: the MCP server that exposes wallet tools to agents

mutx-mcp is intentionally thin. It forwards requests to the TUI over a local Unix socket and does not hold wallet secrets.

What you get

• Wallet operations without handing agents raw private keys
• Manual approval in the TUI when you want direct control
• Bounded autonomy through Short Lived Keys (SLK)
• The same model across local binaries and containers

What MUTX can do

• Create or import Solana wallets
• Send and receive SOL
• List, send, and close SPL token accounts
• Swap through Jupiter or Raydium
• Connect wallets to dApps with WalletConnect
• Manage an address book
• Expose wallet operations over stdio or HTTP through MCP

Start here

• Installation
• Quick Start
• TUI Guide
• MCP Integration

This documentation covers the public operator surface only. Internal services and licensing internals are intentionally excluded.

Getting Started

This section covers how to install mutx-tui and mutx-mcp, then get to a working approval flow with an MCP client.

Installation

You can run MUTX as local binaries or as containers.

Components

• mutx-tui: interactive terminal application; this is the authority process
• mutx-mcp: MCP server; this is the agent-facing process

In normal use, you run both.

Binary install

TUI

Linux x86_64:

curl -LO https://download.mutx.net/tui/latest/mutx-tui-linux-x86_64
chmod +x mutx-tui-linux-x86_64
sudo mv mutx-tui-linux-x86_64 /usr/local/bin/mutx-tui

macOS Intel:

curl -LO https://download.mutx.net/tui/latest/mutx-tui-macos-intel
chmod +x mutx-tui-macos-intel
sudo mv mutx-tui-macos-intel /usr/local/bin/mutx-tui

macOS Apple Silicon:

curl -LO https://download.mutx.net/tui/latest/mutx-tui-macos-arm
chmod +x mutx-tui-macos-arm
sudo mv mutx-tui-macos-arm /usr/local/bin/mutx-tui

MCP server

Linux x86_64:

curl -LO https://download.mutx.net/mcp/latest/mutx-mcp-linux-x86_64
chmod +x mutx-mcp-linux-x86_64
sudo mv mutx-mcp-linux-x86_64 /usr/local/bin/mutx-mcp

macOS Intel:

curl -LO https://download.mutx.net/mcp/latest/mutx-mcp-macos-intel
chmod +x mutx-mcp-macos-intel
sudo mv mutx-mcp-macos-intel /usr/local/bin/mutx-mcp

macOS Apple Silicon:

curl -LO https://download.mutx.net/mcp/latest/mutx-mcp-macos-arm
chmod +x mutx-mcp-macos-arm
sudo mv mutx-mcp-macos-arm /usr/local/bin/mutx-mcp

Verify

mutx-tui --version
mutx-mcp --version

Container images

Published images:

• ghcr.io/mutx-net/tui:latest
• ghcr.io/mutx-net/mcp:latest

Run the TUI interactively:

docker run --rm -it \
  -v "$HOME/.config/mutx:/home/mutx/.config/mutx" \
  -v "$HOME/.local/share/mutx:/home/mutx/.local/share/mutx" \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/tui:latest

Run the MCP server in HTTP mode:

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mcp:latest

The shared /tmp/mutx mount is mandatory. Without it, the MCP container cannot reach the TUI socket and the two processes will not communicate.

Common deployment shapes

Host TUI plus containerized MCP:

mutx-tui

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mcp:latest

Containerized TUI plus containerized MCP:

docker run --rm -it \
  -v "$HOME/.config/mutx:/home/mutx/.config/mutx" \
  -v "$HOME/.local/share/mutx:/home/mutx/.local/share/mutx" \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/tui:latest

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mcp:latest

Quick binary start

If you want the shortest local path, run the binaries directly:

mutx-tui
mutx-mcp

Requirements

• A terminal with TTY support for mutx-tui
• The TUI must be running before mutx-mcp
• Solana RPC access for wallet and swap operations

Continue to Quick Start.

Quick Start

This is the shortest path to a working approval flow.

1. Start the TUI

mutx-tui

On first run, create or import a wallet from the Wallets tab:

1. Press n to create a wallet, or i to import one
2. Choose the network for the wallet
3. Use password protection unless you are testing on throwaway wallets
4. Press r to display the receive address
5. Press b to refresh balances

2. Start the MCP server

Local stdio mode:

mutx-mcp

HTTP mode:

mutx-mcp --mode http --bind 0.0.0.0:8000

3. Connect your MCP client

Minimal local configuration:

{
  "mcpServers": {
    "mutx": {
      "command": "mutx-mcp"
    }
  }
}

If you run the MCP server over HTTP, point your client to /mcp on the chosen host and port.

4. Approve the first request

When the client calls a sensitive tool:

• the request appears in the Requests tab
• press y to approve
• press n to deny

WalletConnect session proposals are handled from the DApps tab rather than the Requests queue.

See the MCP Setup guide for detailed configuration.

TUI Guide

mutx-tui is the primary operator interface. It stores local state, renders approval flows, and is the only process that can unlock wallets and sign.

• Approvals & Requests — Review MCP actions and WalletConnect prompts
• Wallet Management — Create, import, and operate wallets
• Keybindings — Complete keyboard shortcut reference

Approvals & Requests

The Requests tab is the approval surface for MCP-driven actions.

When an agent asks MUTX to do something sensitive without an SLK, the TUI stores the request locally and waits for operator input.

What shows up here

• wallet list exposure requests
• wallet details and balance requests
• receive address requests
• SOL send requests
• swap requests
• address book list and add requests
• SLK creation requests

Approval flow

1. The MCP client calls a tool
2. mutx-mcp forwards the request to mutx-tui
3. The request appears in the TUI
4. You approve with y or deny with n
5. The MCP client receives the result

WalletConnect is separate

WalletConnect does not use the Requests queue for session proposals. Pairings, proposals, and live sessions are handled from the DApps tab.

Request history

Approved and denied requests remain useful as an audit trail:

• d removes a request from the visible history
• e copies the explorer URL when one exists

For deeper troubleshooting, use the Logs tab or the mutx-tui logs export command.

Wallet Management

The Wallets tab is where you create, import, inspect, and operate wallets.

Supported network

Wallet support is currently Solana.

Per wallet you can work against:

• devnet
• testnet
• mainnet
• custom RPC

New wallets default to devnet, which is the safest place to test.

Create a wallet

From the Wallets tab:

1. Press n
2. Enter a wallet name
3. Choose the Solana cluster
4. Choose how the wallet should be protected

Import a wallet

Press i to import from a seed phrase or private key.

Protection modes

• Password (default) — Requires password for sensitive operations
• KeyFile — Uses a local file or remote URL as the encryption key
• Cleartext — No password; suitable only for temporary test wallets

Common actions

With a wallet selected, the default shortcuts are:

• r show receive address
• t transfer SOL
• s open swap flow
• b refresh balances
• h show transaction history
• o toggle token account view
• z close empty token accounts
• x export seed phrase or private key
• m rename wallet
• p pin or unpin wallet in the sidebar
• d delete wallet

Airdrops

The a shortcut requests faucet SOL on devnet and testnet.

Mainnet wallets do not support airdrops.

Wallet details

Press Enter on a wallet to inspect wallet-specific settings and network configuration. This is where custom RPC endpoints and per-wallet settings appear.

Keybindings

All keybindings are configurable. Defaults are listed below.

Global

Wallets

Requests

Address Book

DApps

SLK and Logs

MCP Integration

mutx-mcp exposes MUTX wallet operations to MCP-compatible agents.

The boundary is simple:

• mutx-tui holds local state and wallet access

• mutx-mcp forwards requests to the TUI

• communication between them happens over a Unix socket at /tmp/mutx/mutx.sock

• Setup — Configure the MCP server

• Available Tools — Complete tool reference

• SLK (Short Lived Keys) — Autonomous authorization tokens

MCP Setup

The MCP server supports local stdio transport and streamable HTTP transport.

Prerequisite

Start mutx-tui first. The MCP server expects the TUI socket at:

/tmp/mutx/mutx.sock

You can override the socket path for the TUI with MUTX_SOCKET_PATH or mutx-tui --socket-path ....

stdio mode

mutx-mcp

This is the default mode and the best choice when the agent runs on the same machine.

Example client configuration:

{
  "mcpServers": {
    "mutx": {
      "command": "mutx-mcp"
    }
  }
}

HTTP mode

mutx-mcp --mode http --bind 0.0.0.0:8000

HTTP mode exposes:

• MCP endpoint: http://HOST:8000/mcp
• health check: http://HOST:8000/health

Use this mode when:

• the agent cannot spawn local processes
• you want to front MUTX with a container
• you need a shared MCP endpoint on a trusted local network

Container example

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mcp:latest

If the TUI is also containerized, mount the same /tmp/mutx directory into both containers.

Operational notes

• mutx-mcp is stateless
• if the TUI is not reachable, tool calls fail immediately
• wallet approvals still happen in the TUI, even when MCP is served over HTTP

Available MCP Tools

MUTX exposes 17 MCP tools.

Most tools follow one of these patterns:

• approval in the TUI
• autonomous execution with a valid SLK
• direct execution for low-risk session and token lifecycle operations

Conventions

• Wallets are referenced by short ID or wallet name
• slk is optional on tools that support autonomous execution
• wallet_connect creates a pairing attempt, but the user still approves the WalletConnect proposal inside the TUI

Wallet Tools

Address Book

WalletConnect

SLK Management

Practical flow

Typical agent behavior looks like this:

1. Call wallet_list
2. Choose a wallet ID or name
3. Call read-only tools such as wallet_balance or wallet_receive
4. For sends or swaps, either wait for human approval or use a pre-approved SLK

SLK (Short Lived Keys)

Short Lived Keys allow AI agents to perform wallet operations autonomously within explicit limits.

An SLK is not a wallet key. It is a capability token issued by the TUI and checked on each MCP request.

Requesting an SLK

An agent calls request_slk with desired permissions. The request appears in the TUI’s Requests tab for human approval.

The operator can scope the SLK to specific wallets and address-book entries.

Permissions

• can_balance — View wallet balances
• can_receive — Get receive addresses
• can_send — Send SOL
• can_send_tokens — Send SPL tokens
• can_swap — Swap tokens via DEX
• can_sign — Sign messages

Constraints

• Wallet scope — Which wallets are visible to the SLK
• Address-book scope — Which contacts are visible to the SLK
• max_amount_per_tx — Maximum SOL amount per send
• total_amount — Total SOL budget
• whitelist — Allowed recipient addresses for SOL sends
• allowed_tokens / denied_tokens — Token-level allow or deny rules
• token_constraints — Per-token send budgets
• max_slippage_bps — Maximum allowed slippage for swaps
• duration_secs — Expiry window

Revocation and inspection

• get_slk_info returns status, budget, scope, and permissions
• slk_revoke immediately revokes a token
• revoked or expired SLKs are rejected without user interaction

When to use SLKs

Use an SLK when you want an agent to keep operating within a narrow boundary, for example:

• checking balances periodically
• sending capped payouts to a fixed whitelist
• executing swaps with a strict slippage ceiling

If you do not need autonomy, skip SLKs and keep the default approval flow.

Reference

• Configuration — Paths, overrides, and runtime settings
• Deployment — Binary and container deployment patterns
• FAQ — Frequently asked questions

Configuration

MUTX uses XDG-style paths by default.

Paths

• Config directory: ~/.config/mutx/
• Data directory: ~/.local/share/mutx/
• Bootstrap file: ~/.config/mutx/config.toml
• Default socket path: /tmp/mutx/mutx.sock

After first run, most settings live in the SQLite database under the data directory. The TOML file becomes a minimal bootstrap file, mainly for db_path.

CLI and environment overrides

mutx-tui supports these overrides:

• --config-dir or MUTX_CONFIG_DIR
• --data-dir or MUTX_DATA_DIR
• --socket-path or MUTX_SOCKET_PATH
• --log-file or MUTX_LOG_FILE
• --log-level or MUTX_LOG_LEVEL

Bootstrap example

db_path = "/home/alice/.local/share/mutx/mutx.db"

Runtime settings

The application persists settings such as:

• theme flavor: mocha, latte, macchiato, frappe
• log level
• log-to-file toggle
• vim navigation mode
• hidden balance mode
• dashboard animation toggle
• Solana network defaults and overrides
• custom RPC and explorer URL templates
• keybindings

Solana configuration

Supported default networks:

• devnet
• testnet
• mainnet
• custom

Available global overrides include:

• per-network RPC endpoints
• per-network explorer transaction URLs with {tx}
• per-network explorer address URLs with {addr}
• Jupiter API key
• Raydium API key

Deployment

This page covers the public deployment shapes for MUTX.

Local binaries

This is the simplest setup:

1. Run mutx-tui
2. Run mutx-mcp
3. Configure the agent to spawn mutx-mcp

Use this when the operator, the TUI, and the agent all live on the same host.

Split local TUI plus containerized MCP

This is useful when the agent expects an HTTP endpoint or when you want to keep the MCP runtime isolated.

Requirements:

• TUI running on the host
• shared socket directory mounted into the MCP container

Example:

docker run --rm \
  -p 8000:8000 \
  -v /tmp/mutx:/tmp/mutx \
  ghcr.io/mutx-net/mcp:latest

Fully containerized

You can containerize both components, but the TUI still needs:

• -it for interactive terminal access
• persistent config and data volumes
• a shared /tmp/mutx mount so the MCP container can reach the socket

Health checks

In HTTP mode, the MCP server exposes:

• /health for liveness
• /mcp for the actual MCP transport

Logging

mutx-tui can write structured logs to file and export them with:

mutx-tui logs export

Useful flags:

• --category
• --level
• --since
• --until
• --encrypt

FAQ

General

What blockchains does MUTX support?

Currently Solana.

Is MUTX open source?

No. The public product is distributed as binaries and container images.

Where is my data stored?

All wallet data is stored locally in SQLite databases under ~/.local/share/mutx/. Private keys are encrypted with AES-256-GCM.

Does mutx-mcp store wallet keys?

No. Wallet access stays in mutx-tui. The MCP server forwards requests to the TUI over a local Unix socket.

Does the TUI need to be running for MCP to work?

Yes. mutx-mcp depends on the TUI socket and cannot serve wallet operations by itself.

MCP

Can I run MCP remotely?

Yes, using HTTP mode:

mutx-mcp --mode http --bind 0.0.0.0:8000

The MCP endpoint is /mcp and the health endpoint is /health.

What still requires human approval?

Anything you do without an SLK. request_slk itself also always requires approval.

Can an SLK be revoked immediately?

Yes. Use slk_revoke or revoke it from the TUI.

TUI

Can I use Docker for the TUI?

Yes, but it must run with an interactive TTY and persistent volumes for config, data, and the shared socket directory.

Which tab should I watch during operation?

• Requests for MCP approvals
• DApps for WalletConnect proposals and sessions
• Logs for troubleshooting and audit context