maha-mcp-bridge

Zero-trust local MCP bridge for the Maha Provenance Standard API. Your source data stays on your machine; only sanitized context ever reaches the API.

Install

npm install -g @mahastrategies/maha-mcp-bridge

Related MCP server: Living Atlas MCP

Quick start

maha login    # paste your mhaic_ credential (input hidden), verified live
maha status   # token validity + remaining audit credits
maha logout   # remove the stored credential

Credentials are verified against the live backend before being stored in a user-only file (0600), like the AWS and gcloud CLIs. Set MAHA_MPS_CREDENTIAL instead for CI and containers — it always takes precedence and nothing is written to disk.

MAHA_MPS_API_URL overrides the backend origin (https required, localhost exempt) for staging and local development.

The MCP bridge

maha serve   # stdio MCP server; requires `maha login` first

maha serve refuses to start without a valid credential — an unauthenticated host exposes no tools. Register it with any MCP client, e.g. Claude Code:

{ "mcpServers": { "maha": { "command": "maha", "args": ["serve"] } } }

Tools

Two-tier PII redaction

Before any row or schema reaches the agent it passes through two redaction tiers, and both are counted separately in the ledger:

1. Regex tier (always on, fast): emails, SSNs, payment cards, phones, access/bearer tokens, secret-named fields, plus any custom patterns.

2. Contextual tier (local ONNX model via @huggingface/transformers): a Named Entity Recognition model (Xenova/bert-base-NER) catches free-text PII the regexes miss — PER (people), LOC (locations), ORG (organizations), MISC. It runs entirely on your machine on the native onnxruntime-node backend; the model downloads once to ~/.cache/maha-mcp-bridge/ and never phones home afterward.

The model loads lazily so it never blocks the MCP handshake, and if it can't load (offline, disk, etc.) the bridge degrades to regex-only rather than failing. Disable it with "pii": { "contextual": { "enabled": false } } or MAHA_MPS_DISABLE_NER=1. Redaction is best-effort, not a guarantee that every entity is caught.

The contextual (NER) tier works out of the box. onnxruntime-node ships prebuilt native binaries for macOS, Linux, and Windows (x64 and arm64) inside the npm package, so a plain npm install -g runs the full regex + NER pipeline with no extra flags. (Recent npm prints an npm warn allow-scripts about the package's postinstall; on the supported platforms that script isn't needed — the binary is already bundled.)

You never have to guess which tiers are live: maha status reports the active redaction tier — Redaction regex + NER, regex-only (NER unavailable), or regex-only (NER disabled) — and maha serve prints the same on startup. If your platform has no prebuilt binary, NER is skipped and the bridge degrades to regex-only (safely, not fatally). Only then do you need to rebuild the backend from source:

npm install -g --allow-scripts=onnxruntime-node @mahastrategies/maha-mcp-bridge

Read-only, enforced twice

A statement gate rejects anything that isn't a single SELECT/WITH/SHOW/EXPLAIN/DESCRIBE, and every query then runs inside a server-side READ ONLY transaction that is always rolled back — so a data-modifying CTE that slips past the gate still dies in the database engine.

Configuration

~/.config/maha-mcp-bridge/config.json:

{
  "databases": [
    { "name": "appdb", "kind": "postgres", "urlEnv": "APPDB_URL" },
    { "name": "legacy", "kind": "mysql", "urlEnv": "LEGACY_DB_URL" }
  ],
  "pii": { "customPatterns": [{ "name": "employee_id", "source": "EMP-\\d{6}" }] }
}

Connection URLs come from environment variables (urlEnv); inline url values are rejected if they embed a password. Use a database role with read-only grants as a third layer.

Every tool invocation is recorded in a local, hash-chained SQLite ledger (0600) holding only hashes and redaction counts — never passage text, SQL, or rows.

Configuration (contextual model)

{
  "pii": {
    "contextual": { "enabled": true, "model": "Xenova/bert-base-NER", "minScore": 0.5 }
  }
}

Mount a book

Mount a purchased book as a local MCP server so your agent can navigate it by section instead of scrolling a wall of text:

maha book mount the-imagined-life   # uses your MHAIC token (~/.maha/config.json or MHAIC_TOKEN)

On first use it prompts for your mhaic_ token (input hidden), verifies it, and stores it 0600. Register the mounted book with any MCP client:

{ "mcpServers": { "maha-book-the-imagined-life": { "command": "maha", "args": ["book", "mount", "the-imagined-life"] } } }

maha book mount prints this exact snippet on a successful mount. The book is fetched once (entitlement-checked) and served from memory — the tools are:

The full text of each book is free to read on the web; this structured, agent-queryable form is the paid endpoint. If your token isn't entitled, maha book mount prints the purchase URL instead of starting.

Security notes

• The contextual model runs locally; database rows are never sent anywhere for inference.

• npm audit is clean (0 vulnerabilities). Inference uses the maintained @huggingface/transformers on the native onnxruntime-node backend — no onnxruntime-web/protobufjs. adm-zip (pulled by onnxruntime-node to unpack its native binary) is pinned to a patched ^0.6.0 via a package override.

Why open source

Security teams should be able to audit exactly what leaves the building. The bridge is MIT-licensed; the cloud control plane (billing, idempotent credit ledger, audit engine) is the paid service behind it.