ember MCP server

A gut feeling for coding agents. AI coding assistants like Claude Code, Codex, opencode, and Kilo Code constantly have to decide: start now or ask a question first? Is this test failure real? Is this change safe to push? ember is a small add-on that gives them a quick second opinion at those moments, as a number ("93% likely this needs review"), so they stop interrupting you needlessly and stop making risky changes without asking. You don't call it yourself; your assistant does. It's free and open source, and you choose where the model runs: on your Apple Silicon Mac (32 GB of memory or more, a one-time ~18 GB download), on a server you host, or on one your team already runs. ember advises; the agent decides.

Under the hood, ember runs Cloudflare's Clef-Flash decision model, from its public Hugging Face repo, and exposes it as one MCP tool, advise, that returns a calibrated probability for every option.

Website: shapeandshare.github.io/ember

Ways to run ember

All three are supported equally; ember init asks which one you want.

	On your Mac	On a server you host	On a server someone else runs
Where the model runs	your Apple Silicon Mac	a Mac or an NVIDIA GPU machine you run	wherever its operator runs it
Where your requests go	nowhere: they stay on your Mac	your server	that server
What you need	32 GB of memory, ~18 GB of disk	the server: as for local, or a CUDA GPU; clients: only its address	its address, and a token if it asks for one
Set up with	ember model pull, then ember init	Remote inference or Hosted deployment	ember init --server-url URL

Nothing is ever sent to a server you didn't configure. Without a terminal to ask (a script, CI), ember init sets up local inference; --local or --server-url answer the question up front.

How it works

A decision model is not a chat model: it takes a state plus a schema of typed questions and returns one probability per option, with no text generation. So ember plugs into agents as a tool, while their reasoning stays on their normal LLM:

• The model server (ember/serving/server.py) loads the model once and stays warm across agent sessions.
• The MCP server (ember/mcp/mcp_server.py) never loads the model; it starts the model server on the first tool call, so the MCP handshake stays instant.

Names

Thing	Name
Product, Python import, repository	ember
Distribution (uv tool install, PyPI)	ember-advise, because ember is taken on PyPI and gut is held by an empty project
CLI	ember (short alias: gut; ember-advise too, so uvx ember-advise mcp works)
MCP server / command	ember / ember-mcp
Tool	advise — opencode: ember_advise; Claude Code: mcp__ember__advise (plugin: mcp__plugin_ember_ember__advise); Kilo Code: ember_advise
Playbook skill / MCP resource	ember-advise / ember://guide
Environment variables	EMBER_*

"Clef" always refers to Cloudflare's upstream model, never to this product. Select a model with ember model pull <name> / EMBER_MODEL=<name>; run ember model list to see every registered entry (flash, full).

A hosted deployment (e.g. Outerbounds) that supplies the model's S3 location directly at start time doesn't use this registry at all — see "Hosted deployment: a model location supplied at start time" below.

Verified

Tested versions and hardware are in COMPATIBILITY.md. Current accuracy and latency, from the latest tracked benchmark run, are on the benchmark report.

Install (Apple Silicon)

Requirements

To use a server someone else runs, you need only Python 3.12 (managed by uv) and the server's address; skip ember model pull. To run the model yourself:

• Apple Silicon Mac (M-series) on macOS for local use (MPS). Intel Macs remain out of scope. For a hosted deployment on NVIDIA/CUDA compute (e.g. Outerbounds), see "Hosted deployment" below and deployment/README.md.
• Unified memory above the model's size: 32 GB or more for flash (9B), 96 GB or more for full (27B). Only 128 GB has been verified.
• Disk: about 18 GiB for flash or 55 GiB for full, in Hugging Face's shared cache (~/.cache/huggingface). Config, state, and logs live in ~/Library/Application Support/ember.
• Python 3.12, managed by uv.

uv tool install --python 3.12 ember-advise

ember model pull                   # ~18 GB, resumable, disk-space checked
ember doctor                       # platform, dependencies, model, server, and agent registration
ember init --opencode --global     # register with opencode for every repo on this machine

Keep --python 3.12: uv otherwise picks your newest interpreter, which the pinned torch/transformers stack is not tested on.

This installs the latest released wheel from PyPI.

To pin a specific release tag from GitHub instead (no PyPI required):

uv tool install --python 3.12 "ember-advise @ git+https://github.com/shapeandshare/ember@v0.16.0"

The repository is public, so the git install needs no credentials. To use SSH instead, install from git+ssh://git@github.com/shapeandshare/ember@v0.16.0.

If you manage Python with conda, mamba, or pixi, install the same tool from the interim joshburt channel on Anaconda.org (it moves to conda-forge once that feedstock lands):

conda install -c joshburt -c conda-forge ember-advise   # mamba and pixi take the same flags

Installed ember before the rename, as gut? Run uv tool uninstall gut first: both distributions provide the same commands.

Restart opencode and every repo on this machine gains ember_advise. The model server stays lazy — it starts on the first tool call (or with ember start).

Per-project skill and policy (run once in each repo you want ember-aware agents):

cd /path/to/your/repo
ember agents install --agent opencode  # installs the ember-advise playbook skill
ember agents show snippet >> AGENTS.md # then edit the project policy block at the end

The skill teaches the agent when to consult ember and how to ask; the AGENTS.md snippet adds a project-specific policy you customize (e.g. "check change risk before every push"). See Agent onboarding below for all harnesses and options.

flash targets the commit verified on MPS (17f0b0a) and full its release commit (2f3de3d, not yet verified locally) as a download convenience, and torch/torchvision are pinned to the tested minor series — but ember does not restrict itself to a hand-maintained allowlist of individually verified weights; it runs any model that fits its loader contract (constitution Article V, "Model Loading"). Set EMBER_MODEL_DIR to run another weights directory.

Cloud

ember is Apple-Silicon-first locally, and supports NVIDIA GPUs for hosted deployment (constitution Article VI, "Apple Silicon and CUDA") — three devices total: run it on an Apple Silicon host with the memory above (MPS), on an NVIDIA GPU host (EMBER_DEVICE=cuda, float16 — see "Hosted deployment: a model location supplied at start time" and deployment/README.md for a full Outerbounds example), or on any host with the CPU fallback (EMBER_DEVICE=cpu — float32, roughly twice the memory, much slower). The HTTP server binds to loopback by default; to serve other machines set EMBER_HOST and set EMBER_SERVER_AUTH_TOKEN to require Authorization: Bearer <token> (or any header name via EMBER_AUTH_HEADER, e.g. x-api-key, on the client side). Ember does not terminate TLS — front a remote-serving deployment with a proxy. Clients point at it with EMBER_SERVER_URL. See COMPATIBILITY.md and SECURITY.md.

Agent onboarding

Installing the tool is half the job; the other half is making agents want to consult it at the right moments and read its answers sensibly. ember/agent_kit/ ships that guidance through every channel each agent actually reads:

Channel	opencode	Kilo Code	Claude Code	Codex CLI	How you get it
MCP server instructions (when to consult, how to ask, how to read answers)	✅ in the system prompt	✅ in the system prompt	✅ (2 KB cap)	—	built in, nothing to do
ember://guide resource (full playbook)	✅ via read_mcp_resource	✅ via read_mcp_resource	✅	—	built in
ember-advise skill (playbook, loaded on demand)	✅	✅	✅	✅	ember agents install --agent <agent>
AGENTS.md / CLAUDE.md policy block	✅	✅	✅ (CLAUDE.md)	✅	ember agents show snippet >> AGENTS.md

ember init --opencode                  # opencode: config entry, plugin, and skill
ember init --kilocode                  # Kilo Code: kilo.json entry and skill
ember init --codex                     # Codex CLI: .codex/config.toml entry and skill
ember agents install --agent claude    # .claude/skills/ember-advise/SKILL.md
ember agents install --agent codex     # .agents/skills/... (opencode reads this too)
ember agents show snippet >> AGENTS.md # then edit the project policy at the end

The skill is a playbook, not a reference card: the decision points worth consulting ember about, copy-paste question sets for intent and readiness, failure triage, change risk, routing, and effort, and starting confidence thresholds calibrated from observed model output (re-measured whenever the pinned model revision changes). The snippet ends with a project policy — edit it to wire ember into your own workflow, e.g. "check change risk before every push".

Agent-specific notes:

• opencode reads skills from .opencode/skills, .claude/skills, and .agents/skills, so install one copy per project to avoid duplicate listings.

• Kilo Code: ember init --kilocode writes the mcp.ember entry to kilo.json (same config shape as opencode) and installs the skill to .kilo/skills/ember-advise/SKILL.md; the tool appears as ember_advise. Kilo Code also reads AGENTS.md automatically.

• Claude Code: register the server with claude mcp add --scope user ember -- ember-mcp (every project; drop --scope user to register it for the current project only); the tool appears as mcp__ember__advise. Or install the ember plugin, which bundles the MCP entry and the ember-advise skill (so skip ember agents install --agent claude):

  claude plugin marketplace add shapeandshare/ember
  claude plugin install ember@ember
  

  The plugin still runs the ember-mcp you installed with uv tool install, and its tool appears as mcp__plugin_ember_ember__advise. Use one route, not both, or the tool is listed twice.

• Codex CLI: ember init --codex writes [mcp_servers.ember] to .codex/config.toml (--global: ~/.codex/config.toml, or $CODEX_HOME/config.toml) and installs the skill to .agents/skills/ember-advise/SKILL.md. Codex loads a project .codex/config.toml only for a trusted project, and ember init --codex tells you whether this one is. The entry forwards EMBER_AUTH_TOKEN by name (env_vars), never by value. Support for MCP server instructions and resources is unconfirmed, so rely on the skill and the AGENTS.md snippet there.

Check what's registered

ember doctor closes with two lines per harness: its binary on PATH, and where ember is registered for it — in this directory and globally — or the command that registers it. It only reads each harness's config files; it never runs a harness CLI.

Harness	Register	Project scope	Global scope	doctor also flags
opencode	ember init --opencode [--global]	opencode.json, .opencode/plugins/ember.js	~/.config/opencode/opencode.json, ~/.config/opencode/plugins/ember.js	a leftover mcp.vault entry from older ember init versions
Kilo Code	ember init --kilocode [--global]	kilo.json	~/.config/kilo/kilo.json	—
Codex CLI	ember init --codex [--global]	.codex/config.toml	~/.codex/config.toml	a project file Codex ignores because the project isn't trusted
Claude Code	claude mcp add --scope user ember -- ember-mcp, or the ember@ember plugin	.mcp.json (--scope project); ~/.claude.json per project (--scope local); enabledPlugins in .claude/settings.json / settings.local.json	~/.claude.json; enabledPlugins in ~/.claude/settings.json	a project .mcp.json, which Claude Code asks you to approve

Each harness has its own check too: opencode mcp list, codex mcp list, claude mcp list. Older ember init versions also added this repository's vault MCP server to every config they wrote; if you ran ember init --global, doctor points at the leftover entry in your global opencode config so you can delete it.

ember init records the ember-mcp it finds on your PATH, falling back to the Python that runs it, so run ember init --global from the installed tool (uv tool install …) rather than a checkout's .venv. It merges into existing configs and refuses to rewrite one it can't parse (an opencode.json with comments, say), leaving that file untouched.

CLI

gut is a short alias for every command below.

# lifecycle
ember doctor                      # platform, dependencies, model, server, agent registration
ember serve                       # run the model server in the foreground
ember start | stop | restart | status | logs
ember config path | show
ember uninstall [--purge-models]  # also removes global opencode/Kilo Code/Codex and skill installs

# models
ember model pull [flash|full]      # flash = 9B (default)
ember model list | path [name] | rm [name]

# opencode, Kilo Code, Codex CLI, and agents
ember init [--opencode] [--kilocode] [--codex] [--global] [--local | --server-url URL] [--auth-header NAME]
ember agents install [--agent opencode|claude|codex|kilocode] [--global]
ember agents show instructions|skill|snippet
ember mcp                         # the MCP stdio server agents launch

Usage

Ask the agent in natural language — "Is this bug report urgent, and which team should own it?" — and it calls ember_advise with a state and typed questions:

{
  "model": "clef-flash",
  "answers": {
    "urgent": { "type": "noul", "noul": 0.967 },
    "team": {
      "type": "choice",
      "choice": "db",
      "confidence": 0.9782,
      "probabilities": { "db": 0.9782, "frontend": 0.0218 }
    }
  },
  "usage": {
    "input_tokens": 220, "output_tokens": 0,
    "state_tokens": 34, "fixed_tokens": 186, "media_tokens": 0
  },
  "latency_ms": 930.9
}

Question types: noul (yes/no → P(true)), choice (named options), score (ordered options → expected score plus legend). The model field echoes the upstream model label. usage splits input_tokens into the state, the fixed overhead (questions, schema, prompt wrapper), and any media, so a caller can see what each part of a request cost; the benchmark harness requires this split.

When the evidence is visual, attach images or video frames inline: images is a list of data:image/png;base64,... URIs (or {"content_type": "image/png", "base64": "..."} objects), and videos is a list of videos, each a list of frame refs. Remote URLs and local paths are rejected — the model server never reads host files or fetches URLs for an agent.

Configuration

Settings resolve as CLI flag > environment variable > config file > default. The config file is JSON at ember config path (keys model, host, port, device, max_length, server_url, auth_token, auth_header, allow_insecure_transport, request_timeout, server_auth_token, max_request_length; a max_length of 0 means the model's own maximum, and an unset max_request_length means the loaded model's own default cap).

Variable	Default	Purpose
EMBER_HOST / EMBER_PORT	127.0.0.1 / 8765	Local model server bind address
EMBER_DEVICE	auto	auto, mps, cuda, or cpu
EMBER_TORCH_DISABLE_NATIVE_JIT	1	Disables torch 2.14's torch._native Triton-backed op overrides (e.g. a aten::bmm outer-product specialization Qwen3.5's RoPE forward hits on CUDA), which JIT-compile via a C compiler that a minimal CUDA container (e.g. Outerbounds' Fast Bakery) usually lacks — without this, the first real CUDA request fails with RuntimeError: Failed to find C compiler. Set to 0 on a host with a working compiler toolchain to opt back into the (likely faster) Triton path; has no effect on MPS/CPU
EMBER_MODEL	flash	flash (9B, default) or full (27B), both from Cloudflare's public Hugging Face repos
EMBER_MODEL_DIR	—	Run weights from this directory instead of the pinned cache
EMBER_MAX_LENGTH	0 (the model's maximum: 262,144)	The most tokens the model processes; 0 derives it from the model's config.json, and a larger value is clamped to it
EMBER_MAX_REQUEST_LENGTH	unset: the loaded model's own default, its measured cap or, until measured, its fallback, the longest length that leaves 4 GiB of its memory budget free (24,576 for flash, 65,536 for full). A model outside the registry (EMBER_MODEL_DIR, EMBER_MODEL_S3_URI) gets the lowest registry cap, 24,576 today	Per-request cap on the whole encoded request (state, media, questions, schema, prompt wrapper), checked before inference. A request over it is refused with a 413 that states its token split, never truncated. 0 disables the cap; the maximum still applies
EMBER_SERVER_URL	http://127.0.0.1:8765	Inference endpoint the client sends to; loopback by default, may be remote
EMBER_AUTH_TOKEN	—	Client credential for a remote endpoint
EMBER_AUTH_HEADER	Authorization	Header carrying the credential; Authorization sends Bearer <token>, any other name sends the token verbatim
EMBER_ALLOW_INSECURE_TRANSPORT	0	Allow plaintext http to a non-loopback endpoint (off by default)
EMBER_REQUEST_TIMEOUT	900	Seconds the MCP client waits for each advise request, local or remote. A request near full's cap takes about 12 minutes on an M4 Max, and requests run one at a time, so raise this if long full requests overlap
EMBER_SERVER_AUTH_TOKEN	—	When set, the server requires Authorization: Bearer <token> on /v1/systemone
EMBER_AUTOSTART	1	Let the MCP server start a local server on demand (loopback only)
EMBER_START_TIMEOUT	300	Seconds to wait for the model server to start
EMBER_STATE_DIR	Application Support	Where the pid file and logs live
EMBER_MODEL_S3_URI	—	An s3://bucket/prefix URI naming the exact model location to load — for a deployment (e.g. Outerbounds) that supplies the model's S3 location at start time instead of a REGISTRY key. See "Hosted deployment: a model location supplied at start time" below.
EMBER_S3_ACCESS_KEY_ID / EMBER_S3_SECRET_ACCESS_KEY	—	AWS credentials for EMBER_MODEL_S3_URI. Optional — when unset, boto3's own default credential chain applies (an IAM role attached to the compute, e.g. Outerbounds; env vars; ~/.aws/credentials). Set explicitly only where no role is attached (e.g. a local developer machine)
EMBER_S3_REGION	—	AWS region passed to the S3 client

ember doctor and GET /health (engine) report the limits in force and where each came from: the model, a fallback, an operator setting, or a measured default.

Hosted deployment: a model location supplied at start time

Some deployments (e.g. an Outerbounds app) supply the model's S3 location directly at start time, rather than selecting a REGISTRY entry. Set:

export EMBER_MODEL_S3_URI=s3://my-bucket/clef-flash
export EMBER_DEVICE=cuda   # Outerbounds compute is Linux — no MPS; cuda is the GPU path
ember serve                # foreground, container-friendly (not `ember start`)

No AWS credentials need to be set explicitly when the compute already has an IAM role attached (the expected case on Outerbounds) — boto3's default credential chain picks it up automatically. Set EMBER_S3_ACCESS_KEY_ID/_SECRET_ACCESS_KEY explicitly only where no role is attached.

This is checked once at startup, before the server begins serving, and takes priority over EMBER_MODEL/the model config key entirely — there is no REGISTRY lookup for this path. ember supports any model that can run under its loader contract (constitution Article V, "Model Loading"); it is not a hand-maintained allowlist of individually hash-verified weights, so a URI-supplied location loads directly, with no pin or hash to check against.

Complete Outerbounds deployment examples — flash.yaml/full.yaml (one per model, since they need different compute), a generated requirements.txt, and a make deployment-requirements target — live in deployment/.

Remote inference

Run one server and share it: with your team, with CI, or with a second Mac that lacks the memory for the model. Start the server on the host and point each client at it.

On the host machine (the one with the model)

# Bind to all interfaces so other machines can reach it
EMBER_HOST=0.0.0.0 ember start

# Recommended: also require a bearer token so only your client can use it
EMBER_HOST=0.0.0.0 EMBER_SERVER_AUTH_TOKEN=your-secret ember start

Ember does not terminate TLS. On a trusted LAN, plain HTTP is fine (see the client note below). Over the internet, put a TLS proxy (nginx, Caddy) in front and use https://.

On the client machine (the one running the agent)

export EMBER_SERVER_URL="http://<host-ip>:8765"   # use https:// if behind a TLS proxy
export EMBER_AUTH_TOKEN="your-secret"             # matches EMBER_SERVER_AUTH_TOKEN on the host
export EMBER_AUTOSTART=0                          # nothing local to start
ember status                                      # reports remote endpoint + reachability

Plain http to a non-loopback host is refused by default; set EMBER_ALLOW_INSECURE_TRANSPORT=1 to allow it on a trusted LAN. Credentials may also be sent as a custom header (EMBER_AUTH_HEADER=X-API-KEY). ember status / ember doctor report the endpoint kind, reachability, the remote's advertised auth_required, and whether a credential is configured; reverting to local is a single change (unset these variables).