How to Use Melra: The Beginner's Guide to Gating Risky MCP Tool Calls

How to Use Melra: The Beginner's Guide to Gating Risky MCP Tool Calls

You hand your coding agent a shell, a browser, and your cloud credentials, and then you watch it work. The uncomfortable part comes next: which of those tool calls was safe, which one wrote to production, and who approved it? If your answer is "I was watching the terminal scroll past," you have no safety model — and that is the exact problem this how to use melra guide solves for engineers giving MCP tools to their agents.

Melra — "Modular Execution Layer for Reliable Autonomy" — is an open-source local MCP runtime that sits between your agent and its tools: every tool call passes through Melra's policy gate before it runs, risky actions pause for a human approval, and each finished call leaves a redacted receipt you can audit later. It is made by XAGI Lab (github.com/XAGI-Lab/melra), and it is still alpha software as of November 2026 — so treat everything below as a field guide to a moving target, not a finished product. When a session implicates an HTTP endpoint — an agent claims a URL is healthy, a webhook fired twice — our REST API tester is a handy way to poke those endpoints yourself while Melra re-checks the claim. And since the whole workflow starts inside an MCP client like Claude Code, our Claude Code beginner guide covers the agent side of the pair.

What Is Melra, Exactly?

Melra is a local policy gate for Model Context Protocol tool calls: instead of your agent talking straight to its MCP servers, it talks to Melra, and Melra decides — per call, against a policy file you wrote — whether the call runs, gets blocked, or waits for your approval.

The project lives at github.com/XAGI-Lab/melra. The repo's own badge carries an AGPL-3.0-only license (with the SDKs under Apache-2.0) — note this, because an October 20 writeup describes the whole project as Apache-2.0, which the repo itself contradicts. Melra's first public notice was a Show HN post on October 20, 2026 — the thread itself was not locatable this run — and a my2cents.ai summary the next day captured the pitch: mutations dispatched at most once per task, uncertain outcomes parked for reconciliation instead of replayed. That is the whole philosophy in one line: nothing dangerous runs without a decision, and nothing ambiguous gets replayed.

Melra belongs to the melra local mcp safety niche — a local-first, policy-enforcing MCP runtime rather than a hosted security gateway. If you have felt the "no safety model" problem — watching an agent run shell commands you never reviewed — Melra is the shape of an answer, and it runs on your own machine, not in someone else's cloud.

How Does Melra Sit Between Your Agent and Its Tools?

MCP is the wire your coding agents use to reach tools: the agent speaks the Model Context Protocol, and MCP servers provide tools like run_command, write_file, or fetch. Melra installs itself as an MCP server your agent talks to, then applies your policy before any call reaches the real tool behind it. Your agent's existing workflow does not change shape — it still asks for tools — but every request now passes an interception layer that can allow, block, or hold it for approval.

That position is what makes this a melra mcp runtime tutorial rather than an agent tutorial: you are not learning a new agent, you are learning the gate in front of the tools it already uses. The setup wizard writes Melra into the config file of the MCP client you already run — Claude Code, Cursor, Gemini CLI, VS Code, Zed, Windsurf, OpenClaw, Hermes Agent, GitHub Copilot CLI, the OpenAI Codex CLI, Cline, Amp, Kiro, Goose, Continue — in that client's own config format, keeping your existing content and leaving a .bak backup, per the project's INSTALLATION.md.

Two MCP surface tools do the work once it is wired in: melra_execute, which runs a tool call with approval scoped for mutations, plus harness-mode aliases (approve, write_file, run_command, and friends) when the MELRA_HARNESS_TOOLS=1 flag is set.

How Do You Install Melra and Run the Setup Wizard, Step by Step?

You need Node.js (for npx) or Docker, a project directory, and one supported MCP client installed. The short path is:

1. Open a terminal and cd ~/project — the setup wizard picks your project directory as the agent's workspace (MELRA_WORKSPACE).
2. Run npx @melra/cli@alpha setup. The @alpha tag is intentional: Melra is alpha software, and the README's warning is blunt — APIs may change before 1.0, use an isolated workspace, keep domain and command allowlists narrow, and read every approval before you give it.
3. Answer the wizard's prompts. It detects the MCP clients installed on your machine, writes a safe local policy to ~/.melra/policy.json (it writes safe local defaults once and never overwrites them), and registers Melra into your chosen client's own config file in its own format.
4. Restart the agent app and approve the 'melra' server once when your client asks.
5. Run melra doctor to check that the client configs are wired correctly — or the Docker variant, docker run --rm ghcr.io/xagi-lab/melra:alpha doctor, which needs no local Node install at all.

The docs list alternatives: setup --client cursor --write to target a specific client, a global install, a prebuilt release, or building from source. One caution the docs repeat, stated once here: only install packages under the @melra/ npm scope — an unscoped npm package named melra or a PyPI package named melra is not this project, so check the scope before you install. For the Docker route, our Docker beginner guide covers the container basics behind that doctor command.

What Is the Difference Between Developer Mode and Enforced Mode?

Melra's policies run in one of two modes, and the mode decides whose approval counts. The difference is the single most important thing to understand before you let an agent loose, so read the table slowly.

One more moving part: durable workflows add approval and human_input node types, and answeredBy records who answered (cli:<name> for an operator) — so the audit trail knows whether a human or a process said yes.

How Does Melra Decide Which Calls Need Approval?

Classification is the first decision: reads — read-only commands, file reads, GET/HEAD requests without content — run without approval. Everything else is a mutation, and mutations need declared evidence plus an exact, scoped approval. A policy denial returns status: "blocked" with a reason, not a silent failure — read the reason before you reach for the allowlist.

Policies are operator-written JSON files — ~/.melra/policy.json by default. The knobs, per CAPABILITIES.md:

Every policy decision is recorded with a policyVersion and a policyDigest — the SHA-256 of the policy file's bytes — surfaced on receipts and certificates, so you can always prove which policy allowed which call. Since the policy is a file your team shares, commit it alongside your agent config; our Git beginner guide covers versioning files exactly like this one.

What Happens When Melra Asks for Approval?

When a tool call needs approval, Melra holds the operation and returns an approval phrase; you approve with the task id plus that phrase, and the held operation runs. In developer mode the agent itself can echo the phrase back — which records consent without bounding it — so approvals there are a log of what the agent decided, not a check on it.

In enforced mode there is no phrase and the agent cannot approve itself: a human operator runs melra approve <task-id> in another terminal, or answers in melra console, the operator dashboard. Approvals issued over MCP are refused — only melra judge and console answers count. For "is this the right answer" questions rather than "may it run" ones, Melra can ask an outside human judge through melra_task_judge / melra judge — the semantic evidence type.

Treat the first approval you ever see as a reading exercise, not a reflex click: open the held call, check the tool, its arguments, and the workspace it touches, then decide. The README's own advice — read every approval before you give it — exists because the phrase is one keystroke away from a production write.

What Is a Melra Receipt?

Every action that runs to an outcome leaves a redacted, append-only receipt, plus a certificate carrying its own digest. A receipt records what ran, who asked (the identity chain principal/onBehalfOf — recorded but not authenticated), why it was allowed (the policyDecision with policy version and digest), kernel evidence, and the mode it ran in.

Redaction is aggressive by design: durable task state, receipts, and certificates keep only centrally redacted input, output, and evidence — file contents, browser text, terminal output, typed values, environment values, and URL queries/userinfo are not retained. Secret shapes — PEM and PGP keys, AWS key IDs, JWTs, Slack/GitHub/npm tokens, API keys, auth headers, URL credentials, and password/token/API-key assignments — are stripped via a shared SECRET_PATTERNS list; a value echoed back in an HTTP response is replaced with [REDACTED_CREDENTIAL].

Receipts and certificates live in local SQLite, sealed into a hash chain — melra audit verify detects tampering — and are protected by a local payload key (<MELRA_HOME>/payload.key, mode 0600): lose the key and persisted payloads are unreadable. Telemetry is off by default, and the whole audit trail stays on your machine.

How Does Melra Verify Evidence and Reconcile Ambiguous Writes?

Mutations need declared evidence — predicates the operator writes up front: result_equals, result_contains, file_exists, file_absent, file_hash (SHA-256), exit_code, url_matches, page_contains, http_resource_matches (an independent re-check against the provider — the only "independent"-strength predicate), custom (operator-registered verifier code), and semantic (a yes/no question to an outside human judge). If a required predicate is unmet, the outcome lands at partial — never verified_success.

The kernel also runs its own checks, recorded separately as kernelEvidence: a file write must hash back to exactly the bytes sent, a directory must exist after mkdir, a path must be gone after delete. Declared evidence is what you asked to be true; kernel evidence is what Melra checked itself.

Reconciliation is Melra's answer to the ambiguous mutation: if a mutation reached the wire but no reply came back, nothing is replayed — mutations are dispatched at most once per task, by the project's own design. Instead, a second predicate list is asked against the provider's current state (with {{idempotencyKey}} spliced into the URL), after a settleMs window (30 seconds by default) lets late effects appear. If the provider cannot be reached, the task parks in recovery_required rather than guessing; if no reconciliation predicates were declared, it stays parked for a human.

How Does Melra Compare to withHuman and Cordon?

Three products orbit the same problem — agents taking actions you would have wanted to vet — from different altitudes. The lane lines matter so you do not install the wrong layer.

Read the table once and the rule sticks: withHuman is the approval protocol for coding agents, Cordon is the commercial gateway with a hosted dashboard, and Melra is the local open-source runtime that gates calls on your machine. None of them is a rival of the others — they sit at different layers — and nothing on this site is a CodexFuse-built Melra tool; this is a guide, not a product.

How Do You Keep an Alpha Melra Install Safe?

Melra is alpha, and the README says so in a warning box: APIs may change before 1.0, use an isolated workspace, keep domain and command allowlists narrow, and read every approval before you give it. Honor that box literally: run it against a scratch project directory first, start with enforced mode if anything you care about is in the workspace, and keep forbiddenEffects set to deny mutations until you have watched a few approval cycles.

The beginner's trap with any policy gate is the too-wide first policy — allowing whole shells "to get it working" and forgetting to narrow them. Melra helps a little here: dangerous programs like shells, sudo, powershell, and script hosts are denied even if you list them in allowedCommands by mistake. Still, write the narrow policy first; widening is deliberate work, and an over-broad allowlist teaches the agent nothing.

One honest limitation to carry with you: Melra's own maintainers were soliciting outside-user verification runs in a public issue this month (issue #184), and this guide found no independent hands-on record of a full run — the docs are the authority until more people run it in the wild. Treat the first week as a trial of the gate itself.

What Mistakes Do Beginners Make With Melra?

Sources

1. XAGI-Lab/melra GitHub repo — README, install quick start, repo metadata (created 2026-07-28; 13 stars, 6 forks, 411 commits, 26 releases as of 2026-11-03; AGPL-3.0-only badge, SDKs Apache-2.0). https://github.com/XAGI-Lab/melra

2. Melra docs/INSTALLATION.md — the setup wizard, detected client list, the @melra npm-scope caution, Docker and from-source paths. https://github.com/XAGI-Lab/melra/blob/main/docs/INSTALLATION.md

3. Melra docs/CAPABILITIES.md — policy knobs, developer vs enforced mode, approval behavior, receipts and redaction, evidence predicates, reconciliation. https://github.com/XAGI-Lab/melra/blob/main/docs/CAPABILITIES.md

4. Melra issue #184, "Verify one released MELRA integration in a graphical MCP client" (opened Oct 15, 2026) — maintainers soliciting outside-user verification runs. https://github.com/XAGI-Lab/melra/issues/184

5. my2cents.ai, "Open Source Agent Tools: October 21, 2026" — Show HN October 20 summary (install command, at-most-once mutation dispatch, reconciliation). https://www.my2cents.ai/news/2026-10-21-open-source-agents/

6. Cordon (getcordon.com) — commercial MCP security gateway, verified live 2026-11-03 for the disambiguation. https://getcordon.com/

7. The "how to use melra" SERP checked 2026-11-03 — the exact long-tail is uncontested: Melara/Mela/Malera/Mellerware name-collision noise only, zero independent beginner walkthroughs, zero tool pages.

Frequently Asked Questions

Is Melra free?

It is open source: the repo carries an AGPL-3.0-only license (SDKs Apache-2.0), and there is no paid tier announced — everything runs locally on your machine. Note the correction once: an October 20 secondary writeup calls the project Apache-2.0, but the repo's own badge says AGPL-3.0-only.

Does Melra work with Claude Code?

Yes. The setup wizard detects Claude Code — alongside Cursor, Gemini CLI, VS Code, Zed, Windsurf, OpenClaw, Hermes Agent, GitHub Copilot CLI, the OpenAI Codex CLI, Cline, Amp, Kiro, Goose, and Continue — and writes Melra into that client's own config format. There is also melra launch claude-code, which starts Claude Code in exclusive mode with only the safe tools plus the Melra MCP server.

Will Melra slow down my agent?

Reads run without approval, so the read-heavy parts of a session are untouched; only mutations pause for approval, and flood limits (1,200 calls per minute, 64 pending approvals) bound the queue. No independent performance benchmark was found this run — treat latency as unmeasured until the community runs it in the wild.

Can my agent approve its own actions in Melra?

In developer mode, yes — the agent can echo the approval phrase, which records consent without bounding it. In enforced mode, no: approval must come from a human operator via melra approve <task-id> or melra console, and approvals issued over MCP are refused.

Is Melra the same as Cordon?

No. Cordon (getcordon.com) is a commercial MCP security gateway with a hosted dashboard and Slack approval cards; Melra is a local, open-source runtime you run on your own machine. They share a problem space, not a vendor, not a license, and not a layer.