Omega Brain Mcp

OMEGA BRAIN MCP Governance-First MCP Server — VERITAS Gates · Cryptographic Audit Ledger · Cortex Approval Pipeline

[](https://github.com/VrtxOmega/omega-brain-mcp/actions/workflows/ci.yml)

[](https://glama.ai/mcp/servers/VrtxOmega/omega-brain-mcp)

---

Ecosystem Canon

Omega Brain MCP is the governing cognitive substrate of the VERITAS & Sovereign Ecosystem (Omega Universe). Where other memory layers persist context, Omega Brain enforces it: every execution path passes through the Cortex approval gate, every state transition is sealed to a tamper-proof SHA-3-256 audit ledger, and every artifact claim must survive a 10-gate deterministic build pipeline before a verdict is issued. It does not make trust decisions on behalf of the operator — it enforces the constraints the operator has declared, cryptographically and without exception. In the Omega Universe, Omega Brain MCP is the control plane: the point where agent autonomy ends and declared policy begins.

> SYSTEM INVARIANT: VERITAS Build does not determine whether code is 'good.' VERITAS Build determines whether code survives disciplined attempts to break it under explicitly declared primitives, constraints, test regimes, boundaries, cost models, evidence, and policy.

---

Table of Contents

• [Overview](#overview)
• [Omega Agent Bus](#omega-agent-bus)
• [Features](#features)
• [Architecture](#architecture)
• [Requirements](#requirements)
• [Installation](#installation)
• [Quickstart](#quickstart)
• [Configuration](#configuration)
• [Integrations](#integrations)
• [Usage Examples](#usage-examples)
• [Tools Reference](#tools-reference-26-tools)
• [Resources](#resources-9)
• [CLAEG State Machine](#claeg-state-machine)
• [Troubleshooting](#troubleshooting)
• [Security & Sovereignty](#security--sovereignty)
• [Threat Model](#threat-model)
• [Roadmap](#roadmap)
• [Omega Universe](#omega-universe)
• [License](#license)

---

Overview

What It Is

Omega Brain MCP is a self-contained Model Context Protocol (MCP) server that runs as a local process alongside any MCP-compatible AI client. It exposes 26 tools and 9 resources covering four governance domains:

• Cross-session episodic memory — SQLite vault with full-text search, persisted across all restarts
• 10-gate VERITAS build pipeline — deterministic artifact evaluation from INTAKE through TRACE/SEAL
• Cryptographic S.E.A.L. audit ledger — append-only SHA-3-256 hash chain; every operation is sealed
• Cortex approval gate — Tri-Node similarity gate that enforces declared baseline policy on every tool call

Two Python files. One pip dependency. Zero external services.

Compatible clients: Claude Desktop, VS Code Copilot, Cursor, Windsurf, AutoGen, LangChain, CrewAI, LlamaIndex, and any MCP-compliant host.

Omega Agent Bus

Omega Brain Network is the MCP server and vault. Omega Agent Bus is the cross-agent collaboration layer on top of it — mail, live drain, watchers, roster, and task queue. PCF MCP is a separate stdio server for contribution gates.

| Layer | Name | Doc | |-------|------|-----| | Vault + HTTP MCP | Omega Brain Network | This README | | Agent collaboration | Omega Agent Bus (OMSG) | [docs/OMEGAAGENTBUS.md](docs/OMEGAAGENTBUS.md) | | Contribution gates | PCF MCP | premature-contribution-firewall/docs/MCP.md |

Quick start: enable omega-brain-network.service, copy examples/collaboration-roster.json to ~/.omega-brain/collaboration-roster.json, enable omsg-watch@, drain with omsg-drain --json during active work.

What It Is Not

• Not a cloud service. No network egress, no API keys, no telemetry. All data remains on the operator's machine under ~/.omega-brain/ (or OMEGA_BRAIN_DATA_DIR).
• Not a language model. Omega Brain does not generate text. It governs, routes, stores, and audits agent operations.
• Not a policy authority. VERITAS gates enforce what the operator declares. The system cannot determine correctness beyond what its evidence and constraints describe.
• Not a firewall or OS-level isolation layer. See the [Threat Model](#threat-model) for explicit out-of-scope boundaries.

---

Features

Cross-Session Episodic Memory

• Vault (SQLite + FTS5) — sessions, entries, and events persist across restarts; auto-loaded at startup via omega://session/preload
• Semantic RAG provenance — 3-tier embedding engine: sentence-transformers → fastembed ONNX → TF-IDF n-gram; always available with no GPU requirement
• Sealed handoff — SHA-256 signed cross-session memory file; auto-loaded on restart, auto-written on task seal

10-Gate VERITAS Build Pipeline

Full deterministic evaluation pipeline: INTAKE → TYPE → DEPENDENCY → EVIDENCE → MATH → COST → INCENTIVE → SECURITY → ADVERSARY → TRACE/SEAL

Every gate returns a structured verdict (PASS, MODEL_BOUND, INCONCLUSIVE, or VIOLATION). The pipeline seals the final result as a cryptographically identified record. Fail-fast on VIOLATION by default.

Cryptographic Audit Ledger (S.E.A.L.)

• Append-only SHA-3-256 hash chain
• Every Cortex check, ingest, session log, gate run, and execution is automatically sealed
• Chain integrity is verifiable at any point; any tampered entry breaks the chain
• Persisted to omega_ledger.json under the data directory

Cortex Approval Gate

• Tri-Node similarity gate evaluates every tool call against the operator-declared baseline prompt
• Hard-block window =1.0.0; optional fastembed or sentence-transformers for higher-quality embeddings
• Fully local — no cloud, no API keys, no external server required

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP CLIENT                               │
│   (Claude Desktop / VS Code Copilot / Cursor / AutoGen / ...)   │
└───────────────────────────┬─────────────────────────────────────┘
                            │  MCP stdio / SSE (JSON-RPC 2.0)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   OMEGA BRAIN MCP SERVER                        │
│               omega_brain_mcp_standalone.py                     │
│                                                                 │
│  ┌──────────────────────────┐  ┌──────────────────────────────┐ │
│  │       BRAIN CORE         │  │      VERITAS BUILD GATES     │ │
│  │                          │  │                              │ │
│  │  Cortex Approval Gate    │  │  10-Gate Pipeline            │ │
│  │  (Tri-Node, steer/block) │  │  INTAKE → TYPE → DEPENDENCY  │ │
│  │                          │  │  → EVIDENCE → MATH → COST    │ │
│  │  RAG Provenance Store    │  │  → INCENTIVE → SECURITY      │ │
│  │  (3-tier embeddings)     │  │  → ADVERSARY → TRACE/SEAL    │ │
│  │                          │  │                              │ │
│  │  S.E.A.L. Audit Ledger   │  │  Evidence Engine             │ │
│  │  (SHA-3-256 hash chain)  │  │  (Quality(e), MIS_GREEDY)    │ │
│  │                          │  │                              │ │
│  │  Sealed Handoff          │  │  CLAEG State Machine         │ │
│  │  (SHA-256 cross-session) │  │  NAFE Scanner                │ │
│  └──────────┬───────────────┘  └────────────────┬─────────────┘ │
└─────────────│──────────────────────────────────│───────────────┘
              │                                  │
              ▼  SQLite                          ▼  Pure Python
    ┌─────────────────────┐           ┌─────────────────────────┐
    │   ~/.omega-brain/   │           │  veritas_build_gates.py │
    │   omega_vault.db    │           │  (stateless, no I/O,    │
    │   omega_ledger.json │           │   reproducible verdicts)│
    │   omega_handoff.json│           └─────────────────────────┘
    └─────────────────────┘

Component Roles

| Layer | Component | Role | |-------|-----------|------| | Brain Core | Vault (SQLite) | Persistent session/entry storage with FTS5 full-text search | | Brain Core | S.E.A.L. Ledger | Append-only SHA-3-256 hash chain for tamper-proof audit | | Brain Core | RAG Provenance | Semantic embedding store — 3-tier engine (ST / fastembed / TF-IDF) | | Brain Core | Cortex | Tri-Node approval gate with steer/block modes | | Brain Core | Handoff | SHA-256 sealed cross-session memory transfer | | Build Gates | 10-Gate Pipeline | INTAKE→TYPE→DEPENDENCY→EVIDENCE→MATH→COST→INCENTIVE→SECURITY→ADVERSARY→TRACE/SEAL | | Build Gates | Evidence Engine | Quality(e) formula, MIS\_GREEDY independence scoring, Agreement computation | | Build Gates | CLAEG | Constraint-locked state machine with 3 terminal states | | Build Gates | NAFE Scanner | Narrative failure signature detection and auto-seal |

> 🏛️ Protocol Standard: The omega-brain-mcp is the official execution engine for the [VERITAS Ω-CODE v2.0](../VERITAS-Omega-CODE) specification. The structural gates here enforce the deterministic claims that power veritas-vault session capture, AEGIS remediation, and Sovereign artifacts.

Verdict System

| Verdict | Precedence | Meaning | |---------|-----------|---------| | PASS | 0 (lowest) | All gates satisfied. Artifact is deployable under declared regime. | | MODEL_BOUND | 1 | Gates pass but resource/coverage/confidence near redline. Deploy with monitoring. | | INCONCLUSIVE | 2 | Insufficient evidence or timeout. Cannot affirm or deny. Block deploy. | | VIOLATION | 3 (highest) | Constraint failure, security vulnerability, or test failure. Block deploy. |

---

Requirements

| Requirement | Details | |-------------|---------| | Python | 3.11 or 3.12 | | Core dependency | mcp >= 1.0.0 | | OS | Linux, macOS, Windows (WSL2 recommended on Windows) | | Disk | ~5 MB for source + SQLite data dir (default ~/.omega-brain/) | | Optional | fastembed >= 0.2.0 — ONNX embeddings, ~30 MB model cache, no GPU | | Optional | sentence-transformers >= 2.0.0 + numpy — highest quality embeddings, GPU-capable |

> Embedding engine auto-selection: The server probes for sentence-transformers first, then fastembed, then falls back to built-in TF-IDF n-gram. You always get semantic search — richer models improve recall quality.

---

Installation

From PyPI

pip install omega-brain-mcp

From Source

git clone https://github.com/VrtxOmega/omega-brain-mcp.git
cd omega-brain-mcp
pip install mcp
# Optional: better embeddings
pip install fastembed                       # recommended — fast ONNX, no GPU
pip install sentence-transformers numpy     # best quality, larger download

Docker

docker build -t omega-brain-mcp .
docker run --rm -i omega-brain-mcp                              # stdio mode (MCP standard)
docker run --rm -p 8055:8055 omega-brain-mcp --sse --port 8055  # SSE mode

Run Tests

pip install pytest pytest-asyncio pytest-cov
PYTHONUTF8=1 OMEGA_BRAIN_DATA_DIR=/tmp/omega-test pytest tests/ -v --tb=short

---

Quickstart

1 — Verify the server starts

python omega_brain_mcp_standalone.py --help

2 — Run in stdio mode (default)

The server reads JSON-RPC 2.0 messages from stdin and writes responses to stdout. MCP clients manage this process automatically via the config below.

python omega_brain_mcp_standalone.py

3 — Run in SSE mode (HTTP streaming)

python omega_brain_mcp_standalone.py --sse --port 8055
# GET  http://localhost:8055/sse      — event stream
# POST http://localhost:8055/messages — send tool calls

4 — Test a tool call manually (stdio)

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"omega_brain_status","arguments":{}}}' \
  | python omega_brain_mcp_standalone.py

5 — Configure your MCP client (see [Configuration](#configuration))

---

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "omega-brain": {
      "command": "python",
      "args": ["/absolute/path/to/omega_brain_mcp_standalone.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace (or user settings):

{
  "servers": {
    "omega-brain": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/omega_brain_mcp_standalone.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

Cursor

In Cursor Settings → MCP → Add Server:

{
  "mcpServers": {
    "omega-brain": {
      "command": "python",
      "args": ["/absolute/path/to/omega_brain_mcp_standalone.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

Windsurf / Cascade

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "omega-brain": {
      "command": "python",
      "args": ["/absolute/path/to/omega_brain_mcp_standalone.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

SSE / HTTP Client

{
  "mcpServers": {
    "omega-brain": {
      "type": "sse",
      "url": "http://localhost:8055/sse"
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PYTHONUTF8 | 0 | Set to 1 on Windows to avoid encoding errors | | OMEGA_BRAIN_DATA_DIR | ~/.omega-brain/ | Override the data directory for vault, ledger, and handoff files |

---

Integrations

Omega Brain MCP integrates with any MCP-compatible client using standard JSON-RPC 2.0 over stdio or SSE. For framework-specific integration patterns (LangChain, CrewAI, AutoGen, LlamaIndex) see [INTEGRATIONS.md](INTEGRATIONS.md) and the [examples/](examples/) directory.

Recommended Integration Pattern

For production use, keep one persistent server process across all calls. This avoids the 2–3s cold-start cost of loading the embedding model and SQLite on every call.

from omega_client import OmegaBrainClient

client = OmegaBrainClient()  # starts server subprocess once

# Governance-first: always run a Cortex check before executing
check = client.call("omega_cortex_check", {
    "tool": "omega_rag_query",
    "args": {"query": "sensitive project data"},
    "baseline_prompt": "You are a data analysis agent. Only access approved datasets."
})
# {"approved": true, "similarity": 0.71, "verdict": "APPROVED", "node_votes": [1, 1, 1]}

# Memory retrieval
result = client.call("omega_rag_query", {"query": "VERITAS evidence thresholds", "top_k": 5})

# Run VERITAS build gate pipeline
verdict = client.call("veritas_run_pipeline", {"claim": {...}, "regime": "baseline"})

# Session persistence — always seal before terminating
client.call("omega_seal_task", {})
client.close()

Quick-Reference Pattern Table

| Goal | Tool | Notes | |---|---|---| | Pre-action guard (binary) | omega_cortex_check | Returns approved: true/false | | Pre-action guard + auto-fix | omega_cortex_steer | Returns steered args if in 0.45–0.65 window | | Full Cortex-wrapped execution | omega_execute | Omega Brain tools only; returns steered_args for external tools | | Memory / context retrieval | omega_rag_query / omega_preload_context | Use at agent task start | | Human-readable audit | omega_brain_report | SEAL chain tail, blocked count, VERITAS avg | | Session persistence | omega_seal_task | One call, no fields required | | Full artifact evaluation | veritas_run_pipeline | 10-gate deterministic verdict + seal hash |

---

Usage Examples

All examples use JSON-RPC 2.0. In practice, your MCP client sends these automatically when you invoke a tool. The shell one-liner form is useful for testing.

Check server health

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"omeg

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [VrtxOmega](https://github.com/VrtxOmega)
- **Source:** [VrtxOmega/omega-brain-mcp](https://github.com/VrtxOmega/omega-brain-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.