Quickstart

Install Rust via rustup, then build UMB from source. A release build is optimized, LTO-linked, and stripped — typically 3–8 MB.

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ source "$HOME/.cargo/env"

$ git clone https://github.com/david-burley/umb
$ cd umb
$ cargo build --release
# binary → target/release/umb

Prefer a prebuilt binary? Grab one from the download page (macOS, Linux, Windows) or the GitHub releases.

UMB reads ~/.umb/servers.json. It uses the standard MCP server format — the same shape as .mcp.json or claude_desktop_config.json.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" }
    }
  }
}

Add as many servers as you like — there is no limit. Edit this file while UMB is running and changes hot-swap automatically, with no restart.

UMB runs as an MCP server over stdio. Add it to your agent's MCP configuration the same way you would any stdio server — point the command at the umb binary.

{
  "mcpServers": {
    "umb": {
      "command": "/path/to/umb"
    }
  }
}

That's it. Your agent now sees three meta-tools instead of every tool from every server — and reaches all of them through UMB.

UMB is a stdio MCP server, so any agent that can launch a local MCP binary can use it. Each harness below does the same thing — point its MCP config at the umb binary. What UMB then exposes is whatever you registered in ~/.umb/servers.json above.

Claude Code — add it from the CLI (user scope), or commit an .mcp.json for project scope.

$ claude mcp add umb -- /path/to/umb

# or project-scoped .mcp.json:
{ "mcpServers": { "umb": { "command": "/path/to/umb" } } }

opencode — under the mcp key, a local server takes a command array.

{
  "mcp": {
    "umb": { "type": "local", "command": ["umb"], "enabled": true }
  }
}

Cursor / Windsurf / generic — the portable mcpServers block works across most clients (Cursor ~/.cursor/mcp.json, Windsurf, Cline, Zed).

{
  "mcpServers": {
    "umb": { "command": "umb", "args": [] }
  }
}

Hermes Agent (Nous Research) — reads ~/.hermes/config.yaml under mcp_servers; stdio is supported, so UMB runs directly.

mcp_servers:
  umb:
    command: "umb"
    args: []
    enabled: true

OpenClaw — add it with the CLI; definitions are stored under mcp.servers in ~/.openclaw/openclaw.json.

$ openclaw mcp add umb --command umb
$ openclaw mcp doctor umb --probe

UMB serves stdio only. The sse / http entry types in servers.json describe the backing servers UMB connects to — not a way to reach UMB itself. If a harness can only talk to remote MCP servers, run UMB behind an mcp-proxy-style stdio→HTTP adapter. Full per-harness detail lives in docs/INTEGRATIONS.md.

UMB exposes a minimal API. The agent works through these instead of ingesting hundreds of raw tool definitions.

Built-in file and shell tools are also provided directly by UMB. The protocol uses JSON-RPC 2.0; tools/list and tools/call are accepted as aliases.

Run one shared backend and connect lightweight proxies to it, so multiple agent sessions reuse a single warm process.

# terminal 1 — start the shared daemon
$ umb --daemon

# each agent — connect via a lightweight proxy
$ umb --proxy

If a session ever leaves an orphaned daemon behind, umb doctor finds and cleans it up. It's pure local introspection — no network, no telemetry.

$ umb --doctor            # read-only scan
$ umb --doctor --clean    # terminate orphans (prompts first)
$ umb --doctor --json     # machine-readable output