1. Home
  2. MCP Gateways & Proxies
  3. MELRA

MELRA

MELRA MCP Server

MELRA is an alpha, local MCP runtime that governs agent tool calls routed through it. Each action is planned, policy-checked, approved when it changes something, executed at most once, verified against declared evidence and recorded in a redacted receipt.

View repositoryInstall & configure

Server facts

MELRA MCP Server

Project

Author
XAGI-Lab
Repository
github.com/XAGI-Lab/melra
Website
xagilab.com
License
Apache-2.0
Category
MCP Gateways & Proxies

Tech

Runtime / language
nodeTypeScript
Transports
stdio
Remote available
No
Authentication
Not specified

Activity

GitHub stars
12
Last commit
Data as of

Tags

  • Local First
  • Typescript
  • agent safety
  • approval
  • audit
  • mcp security
  • tool calling

Overview

MELRA, short for Modular Execution Layer for Reliable Autonomy, is a local runtime placed between an agent and the actions it requests. Instead of many task-specific tools, it exposes twelve kernel operations. An agent first calls melra_plan with one bounded operation, such as a file write, terminal command, browser action or HTTP request, together with evidence that would prove success; nothing runs during planning. melra_execute then rechecks policy, dispatches the effect once under a budget, verifies the declared evidence and stores a redacted, hash-linked receipt. Changes require an exact, expiring approval, given as a phrase in developer mode or through an operator command in enforced mode. When a crash leaves an outcome uncertain, the task waits in recovery_required rather than being retried. Durable workflows resume after restarts.

Shipped adapters cover files, terminal, browser, desktop control and HTTP; database, cloud and SaaS adapters remain roadmap items. Defaults are conservative: stdio, loopback HTTP or a private Unix socket, telemetry off, paths confined to the workspace, shells denied and private network addresses blocked. A setup command writes the server entry into the configuration of 26 supported MCP clients. MELRA only governs calls sent through it, and exactly-once external effects still depend on each provider. It is alpha software, requires Node.js 22.13 or newer, and ships on npm as @melra/cli under the Apache-2.0 license.

Install & configure

Requirements

  • Node.js 22.13 or newer, or 23.4 or newer
  • Chrome, Chromium or Edge for browser tasks
  • An MCP-compatible client
Documented launch / install command
npx @melra/cli@alpha setup

Running npx @melra/cli@alpha setup in the project directory writes this entry into a detected client's config and creates a local policy. MELRA_HOME defaults to ~/.melra and MELRA_POLICY is optional. Back up the payload.key file in MELRA_HOME together with the SQLite files. Pin an exact version instead of @alpha to stay on one release.

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Desktop configuration
{
  "mcpServers": {
    "melra": {
      "command": "npx",
      "args": [
        "-y",
        "@melra/cli@alpha",
        "serve"
      ],
      "env": {
        "MELRA_WORKSPACE": "<absolute path to the agent's workspace>",
        "MELRA_HOME": "<absolute path to a local MELRA data directory>",
        "MELRA_POLICY": "<absolute path to policy.json>"
      }
    }
  }
}

Read the Claude Desktop setup guide

Config file · Project: .cursor/mcp.json

User: ~/.cursor/mcp.json

The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.

Cursor configuration
{
  "mcpServers": {
    "melra": {
      "command": "npx",
      "args": [
        "-y",
        "@melra/cli@alpha",
        "serve"
      ],
      "env": {
        "MELRA_WORKSPACE": "<absolute path to the agent's workspace>",
        "MELRA_HOME": "<absolute path to a local MELRA data directory>",
        "MELRA_POLICY": "<absolute path to policy.json>"
      }
    }
  }
}

Read the Cursor setup guide

Config file · Workspace: .vscode/mcp.json

For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.

VS Code configuration
{
  "servers": {
    "melra": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@melra/cli@alpha",
        "serve"
      ],
      "env": {
        "MELRA_WORKSPACE": "<absolute path to the agent's workspace>",
        "MELRA_HOME": "<absolute path to a local MELRA data directory>",
        "MELRA_POLICY": "<absolute path to policy.json>"
      }
    }
  }
}

Read the VS Code setup guide

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.

Windsurf configuration
{
  "mcpServers": {
    "melra": {
      "command": "npx",
      "args": [
        "-y",
        "@melra/cli@alpha",
        "serve"
      ],
      "env": {
        "MELRA_WORKSPACE": "<absolute path to the agent's workspace>",
        "MELRA_HOME": "<absolute path to a local MELRA data directory>",
        "MELRA_POLICY": "<absolute path to policy.json>"
      }
    }
  }
}

Read the Windsurf setup guide

Config file · Project scope: .mcp.json at the repository root

The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Code configuration
{
  "mcpServers": {
    "melra": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@melra/cli@alpha",
        "serve"
      ],
      "env": {
        "MELRA_WORKSPACE": "<absolute path to the agent's workspace>",
        "MELRA_HOME": "<absolute path to a local MELRA data directory>",
        "MELRA_POLICY": "<absolute path to policy.json>"
      }
    }
  }
}

Read the Claude Code setup guide

Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.

Tools

Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.

ToolWhat it does
melra_capabilitiesDiscover supported operations, platform support, limits and policy posture.
melra_planValidate, store and policy-check one bounded operation without running it.
melra_executeRun an approved plan and verify its declared outcome.
melra_task_statusRead the durable state of a task.
melra_task_cancelCooperatively cancel pending or running work.
melra_receiptFetch the redacted evidence and execution certificate for a task.
melra_task_judgeAnswer a waiting task's semantic question with yes, no or cannot_tell.
melra_workflow_planValidate, preflight, encrypt and store a bounded workflow.
melra_workflow_advanceExecute the next ready scheduling wave of a workflow.
melra_workflow_statusRead the durable projection of a workflow.
melra_workflow_cancelCooperatively cancel unfinished workflow work.
melra_workflow_controlPause, resume or suspend a workflow run without losing its place.

Use cases

  • Require explicit approval before an agent writes files, runs commands or sends HTTP mutations.
  • Confirm that an action succeeded against declared evidence such as an exit code or file contents.
  • Keep an auditable, redacted receipt of each governed tool call.
  • Run multi-step workflows that survive process restarts without replaying uncertain changes.

Strengths

  • Plan and execute are separate calls, and policy is checked again at execution time.
  • Uncertain mutations park in recovery_required instead of being replayed.
  • Local-only defaults with telemetry off and workspace-confined paths.

Limitations

  • Alpha software; behavior and interfaces may change between releases.
  • Only governs calls routed through it; other agent tools remain outside its control.
  • Database, cloud and SaaS adapters are on the roadmap, not shipped.

MELRA setup notes

  • Check MELRA_HOME, MELRA_POLICY, MELRA_WORKSPACE in the MELRA configuration if startup or authentication fails.
  • MELRA's stdio example needs a client that launches local processes.

Frequently asked questions

Only tool calls routed through it. It handles each effect through its own adapters for files, terminal, browser, desktop control and HTTP; calls made through other tools stay outside its control.

Developer mode, the default, approves changes with an exact phrase and accepts that the agent may have other paths. Enforced mode asserts the agent is sandboxed: approvals come from melra approve, unsafe-local mode is refused and nothing binds outside loopback.

Yes. Setting MELRA_HARNESS_TOOLS=1 adds plainly named tools such as read_file and run_command; each one still runs through the same plan, approval and verification pipeline.

Use the @melra/cli package on npm or the GitHub releases. The README warns that an unscoped melra package on npm or PyPI is not this project.

Related MCP servers

  1. pluggedin-mcp-proxy
  2. pluggedin-mcp
  3. Supergateway
  4. Unla MCP Gateway
  5. mcp-proxy
  6. mcpo
  7. MCPHub
  8. ContextForge