Lema MCP

lema-mcp

Your coding agent can read the code. It can't read the _argument_ behind it. lema-mcp gives your agent the recorded *why* — and the alternatives a project already ruled out — cited to the source. For React, Kubernetes, and Rust out of the box, and for your own repo with one command.

A local MCP server. No account, no database, no network for your own repo — install it in 30 seconds and ask why a project decided something, or whether the approach you're about to take was already rejected.

---

❌ Without lema

• The agent invents the why from training recall — fluently, and sometimes wrongly. The rationale lives in RFC / KEP / PR threads; it was never in the code.
• It re-proposes the approach the maintainers already rejected two years ago — because a rejected alternative leaves *no trace* in the source.
• Ask "was this ever ruled out?" and you get a confident guess, with no way to tell a real ruling from a hallucinated one.

✅ With lema

• One cited answer from the project's actual recorded deliberation — every [n] links to the RFC / PR where the call was made.
• A typed `ruled_out` verdict when a project already rejected your approach, with the recorded reason *and* a pointer to where the docs say to do it instead.
• A typed `settled` verdict when your approach *is* the project's in-force recorded choice — the governing decision cited, with a docs pointer for the how.
• An honest "no recorded ruling" when the record is silent — which means *unknown*, not *approved*. lema never fills the gap with a guess.

lema holds reasoning — why a decision was made, what was rejected — not API

syntax or code samples. For those, reach for a docs tool. lema is the right place

for *why*.

---

Try it in 30 seconds — no account

npx lema-mcp try react        # or: kubernetes · rust

That writes a read-only public server to your project's .mcp.json. Reload your agent's MCP servers (in Claude Code: /mcp) and try the flagship tool, `check_approach` — name a direction, get the recorded verdict:

> "Let's add a delayMs prop to Suspense to debounce the fallback."   (repo: react)

⛔ ruled_out — the React team considered and rejected this. " " [1] Where to look instead → https://react.dev/reference/react [1] reactjs/rfcs#212

"I'll add a global event bus for cross-component communication." (repo: react)

◦ no_recorded_ruling — React's public record doesn't settle this. (Unknown — not approved.)

Or just ask in plain language — *"why did React adopt Hooks over mixins?"* — and get one cited answer, with an honest abstain when the record is silent.

Covered today: React · Kubernetes · Rust, served from lema's public API (api.lema.sh). Tokenless. It's a curated three-project demo corpus — not analytics over a graph you own.

---

Install

No-account public demo (React's recorded decisions, zero setup):

If the Cursor button doesn't open an install prompt (common when the browser can't hand off the cursor:// deeplink), paste this into .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

"mcpServers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"], "env": { "LEMA_MCP_MODE": "public", "LEMA_PUBLIC_REPO": "react-rfcs" } } } }

That drops you into React's public record — ask *"why did React rule out X?"* and get a cited answer, no account. To wire your own repo for capture, or point the demo at Kubernetes or Rust, use the per-client setup below.

npx needs only Node — no Go toolchain, no account. Two commands cover both ways to use lema:

npx lema-mcp try react   # read-only: ask React/Kubernetes/Rust why + what's ruled out

npx lema-mcp init # your repo: decision capture + the never-reopen guard

Both are non-destructive and idempotent — they merge into existing config and re-running changes nothing. init and try share the same lema server key; the authed init server is a superset (it serves the public tools too), so the two coexist and try never downgrades it.

Claude Code

Easiest — let lema write the config and hooks for you:

npx lema-mcp init        # or: npx lema-mcp try react

Or add it by hand to .mcp.json (this gets the read + capture tools, but not the guard/nudge hooks that init installs):

{

"mcpServers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] } } }

</details>

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

"mcpServers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] } } }

For the no-account public demo instead, add the env block:

{

"mcpServers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"], "env": { "LEMA_MCP_MODE": "public", "LEMA_PUBLIC_REPO": "react-rfcs" } } } }

</details>

Claude Desktop

Settings → Developer → Edit Config, then add to mcpServers:

{

"mcpServers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"], "env": { "LEMA_MCP_MODE": "public", "LEMA_PUBLIC_REPO": "react-rfcs" } } } }

</details>

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] } } }

</details>

VS Code (GitHub Copilot)

Add to .vscode/mcp.json — note VS Code uses the servers key:

{

"servers": { "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] } } }

</details>

Go install / pinned binary

go install github.com/lemahq/lema-mcp/cmd/lema-mcp@latest

For the public demo, set LEMA_MCP_MODE=public and LEMA_PUBLIC_REPO=react-rfcs (k8s-enhancements · rust-rfcs). The public API URL is baked into the binary.

The public config sets only LEMA_MCP_MODE + LEMA_PUBLIC_REPO (react-rfcs · k8s-enhancements · rust-rfcs) — the API URL is compiled in.

Hosted teams: sign in once; the repository resolves automatically

After you sign in to Lema, save one Organization-scoped credential outside your repositories. The normal setup contains identity credentials, not a copied workspace UUID:

# ~/.config/lema/credentials

LEMA_API_URL=https://api.lema.sh LEMA_API_TOKEN=lema_live_...

chmod 600 ~/.config/lema/credentials

npx lema-mcp@latest doctor context

Restart the coding agent after changing MCP configuration. From then on, Lema matches the checkout's verified Git remote to a Repository, finds its Project, and passes one immutable target receipt to every operation. Opening two repositories in parallel does not create a mutable “active repository,” and each user keeps their own Organization-scoped credential.

For multi-repo Projects, ambiguity recovery, repositories without a remote, worktrees, and compatibility overrides, read Target context: Projects, repositories, and Runs.

---

Two ways to use it

1. The public record — React, Kubernetes, Rust (read-only, no account)

Ask why a popular project decided something, or check whether a direction was already rejected, over its recorded RFC/KEP deliberation. This is the try server.

2. Your own repo — capture + never-reopen (local, no account)

Most "context" tools are read-only — a nicer way to grep your docs. lema reads too, but its real job is never-reopen:

• Your agent settles a choice → it calls `record_decision` with the option it chose and the alternatives it rejected, with why each was killed (the part that never survives into the code).
• Before anyone proposes a direction → `check_decided` returns the prior decision if that option is CLOSED.
• On every edit, a PreToolUse guard hook (installed by init) reads the draft change and surfaces a CLOSED decision *before* the dead option gets re-proposed — enforced off both your captured decisions and the repo's own ADRs.

Decisions are captured to .lema/decisions.jsonl — a plain append-only file you commit, so your whole team's agents share the same memory through git. No key, no LLM call on our side: your agent forms the decision; lema stores it and serves it back.

What never-reopen looks like

Your agent reaches for an option you already killed — and it comes back CLOSED, with the original reason attached:

⛔ CLOSED — do not propose "SWR": no first-class mutation / cache

invalidation — we'd hand-roll it *(decided 2026-06-04 · "Data fetching for the

web app" · chose TanStack Query)*

So the agent surfaces the prior decision instead of re-litigating it. Supersede a decision and the *previously chosen* option goes CLOSED too — enforced both ways. (That's the real output of npx lema-mcp demo, run against a throwaway temp dir.)

The guard is advisory and fail-open: in its default context mode it injects that note as a non-blocking nudge — it never hard-blocks and never auto-approves an edit. LEMA_GUARD_MODE=ask prompts *you* on a strong match; off is a kill switch. Any error → it emits nothing and gets out of the way.

---

Available tools

Your agent calls these over MCP.

The public record (no account)

Your own repo

| `get_decision` · `list_decisions` · `get_decision_graph` | One decision's full body; th