nexus-mcp-enterprise-gateway

🌐 Nexus MCP Enterprise Gateway

Enterprise Model Context Protocol (MCP) Server Mesh, Execution Sandbox & Observability Gateway

---

🏛️ Executive Summary

While Anthropic's Model Context Protocol (MCP) has become the universal standard connecting LLMs to external systems, standard reference implementations lack enterprise-grade controls. In production environments across regulated industries (energy, banking, healthcare), connecting autonomous agents directly to internal tools exposes organizations to:

1. Unchecked Data Egress: Unmasked PII, credentials, or proprietary concession identifiers leaking into LLM context windows.
2. Unauthorized Destructive Executions: LLMs generating unintended DROP, DELETE, or state-altering commands without operator clearance.
3. Observability Blindspots: Lack of token attribution, latency tracking, and audit traces for compliance verification.

Nexus MCP Enterprise Gateway resolves these operational challenges by introducing a hardened intermediary layer that implements the standard MCP JSON-RPC 2.0 specification (2024-11-05) alongside enterprise controls:

• Hierarchical RBAC Enforcement: Automatically filters registered tools, resources, and prompt templates based on caller identity (ANALYST, AUDITOR, ADMIN, SUPERUSER).
• Real-Time DLP & PII Sanitizer: High-precision regex scrubbers intercepting emails, credit card numbers, national identification numbers (BVN/NIN/SSN), and connection strings across both tool inputs and LLM outputs.
• Human-In-The-Loop (HITL) Cryptographic Approval Gates: Intercepts high-risk operations (e.g., status changes, resource mutations) and generates HMAC-SHA256 approval tickets requiring explicit administrator clearance.
• OpenTelemetry Distributed Tracing: Emits microsecond-resolution execution spans (trace_id, span_id, duration, token consumption, status codes) compatible with modern observability platforms.

---

🏗️ Architecture Overview

graph TD
    subgraph ClientLayer [Agent & Client Layer]
        A[Claude Desktop / Cursor / Web Studio]
    end

    subgraph GatewayLayer [Nexus MCP Enterprise Gateway]
        B[JSON-RPC 2.0 Protocol Dispatcher]
        C[Sliding-Window Rate Limiter & Token Budget]
        D[Hierarchical RBAC Policy Engine]
        E[HITL Cryptographic Approval Gate]
        F[Execution Sandbox & JSON Schema Validator]
        G[PII & Sensitive Data Redaction Filter]
        H[OpenTelemetry Trace Collector]
    end

    subgraph EnterpriseBackends [Enterprise Data Adapters]
        I[(SQLite / SQL Production Assets)]
        J[Financial & Cash-Call Reconciler]
        K[Host SCADA / OS Telemetry]
        L[Enterprise SOP & Policy Store]
    end

    A -->|JSON-RPC Request| B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> I & J & K & L
    I & J & K & L --> G
    G --> H
    H -->|JSON-RPC Response| A

---

🛡️ Enterprise Security & DLP Specifications

1. Role-Based Access Control (RBAC) Matrix

Persona	Level	Permitted Operations	Restricted Capabilities
ANALYST	10	sql_query (Read-Only), reconcile_cash_call, search_enterprise_docs	Cannot execute destructive SQL, cannot access admin tools
AUDITOR	20	All Analyst capabilities + Full trace telemetry inspection (nexus/traces)	Cannot approve HITL tickets
ADMIN	30	All Analyst & Auditor capabilities + SQL mutations + update_concession_status	Must approve high-risk tickets
SUPERUSER	40	System-level runtime configurations and gateway policy overrides	None

2. High-Precision DLP Redaction Engine

All inputs and responses pass through the PIISanitizer to enforce zero secret and identity leakage:

Target Category	Detection Method	Replacement Token
Corporate Email Addresses	RFC 5322 Regex Scan	[REDACTED_EMAIL]
Payment Cards (Visa/Mastercard)	16-digit bounded formatting	[REDACTED_PAYMENT_CARD]
National IDs & Banking Tokens	11-digit BVN/NIN & 9-digit SSN	[REDACTED_NATIONAL_ID]
Database Connection Strings	Protocol schema patterns (postgres://, etc.)	[REDACTED_CONNECTION_STRING]
Bearer Tokens & API Keys	Key entropy & assignment patterns	[REDACTED_SECRET]

---

⚡ Algorithmic Complexity & Performance Metrics

Component	Algorithm / Mechanism	Time Complexity	Space Complexity
Rate Limiter	Sliding-Window deque eviction	$O(1)$ amortized	$O(W)$ per client
RBAC Evaluator	Integer level hierarchy lookup	$O(1)$	$O(1)$
Approval Tickets	HMAC-SHA256 digest hashing	$O(N)$ on params	$O(1)$
DLP Sanitizer	Precompiled DFA regular expressions	$O(M)$ on text length	$O(M)$
Sandbox Execution	Async timeout wrapping via asyncio.wait_for	$O(1)$ overhead	$O(1)$

---

🚀 Step-by-Step Setup & Execution

Prerequisites

• Python 3.11+ (Fully verified on Python 3.14 on Windows & Linux)
• Git

1. Clone & Install Dependencies

# Clone repository
git clone https://github.com/JayNabasu/nexus-mcp-enterprise-gateway.git
cd nexus-mcp-enterprise-gateway

# Install dependencies
pip install -r requirements.txt

2. Execute Automated Verification Suite

# Run the complete test suite (21 unit & integration tests)
python -m pytest tests/ -v

Verified Test Output:

============================= test session starts =============================
platform win32 -- Python 3.14.4, pytest-9.1.0, pluggy-1.6.0
rootdir: C:\...\nexus-mcp-enterprise-gateway
collected 21 items

tests/test_adapters.py::test_sql_adapter_select PASSED                   [  4%]
tests/test_adapters.py::test_sql_adapter_blocks_destructive_query PASSED [  9%]
tests/test_adapters.py::test_sql_adapter_allows_admin_mutation PASSED    [ 14%]
tests/test_adapters.py::test_financial_reconciliation_math PASSED        [ 19%]
tests/test_adapters.py::test_system_telemetry PASSED                     [ 23%]
tests/test_adapters.py::test_doc_adapter_search PASSED                   [ 28%]
tests/test_protocol.py::test_jsonrpc_request_serialization PASSED        [ 33%]
tests/test_protocol.py::test_jsonrpc_response_success PASSED             [ 38%]
tests/test_protocol.py::test_jsonrpc_response_error PASSED               [ 42%]
tests/test_protocol.py::test_tool_definition_model PASSED                [ 47%]
tests/test_sandbox.py::test_sandbox_timeout PASSED                       [ 52%]
tests/test_sandbox.py::test_sandbox_schema_validation PASSED             [ 57%]
tests/test_security.py::test_rbac_hierarchy PASSED                       [ 61%]
tests/test_security.py::test_pii_sanitization PASSED                     [ 66%]
tests/test_security.py::test_pii_nested_dict_sanitization PASSED         [ 71%]
tests/test_security.py::test_hitl_approval_gate_workflow PASSED          [ 76%]
tests/test_server.py::test_server_initialize PASSED                      [ 80%]
tests/test_server.py::test_tools_list_role_filtering PASSED              [ 85%]
tests/test_server.py::test_tools_call_sql_query PASSED                   [ 90%]
tests/test_server.py::test_tools_call_financial_reconciliation PASSED    [ 95%]
tests/test_server.py::test_resources_and_prompts PASSED                  [100%]

============================= 21 passed in 0.54s ==============================

3. Launch HTTP & Web Studio Mode

python server_cli.py --mode http --port 8000

Open http://localhost:8000 in any browser to access the interactive MCP Studio.

4. Launch STDIO Mode (For Claude Desktop / IDE Agents)

Configure in Claude Desktop or Antigravity configuration:

{
  "mcpServers": {
    "nexus-gateway": {
      "command": "python",
      "args": ["C:/path/to/nexus-mcp-enterprise-gateway/server_cli.py", "--mode", "stdio"]
    }
  }
}

---

📡 MCP Protocol Reference Examples

tools/call Request Frame

{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "tools/call",
  "params": {
    "name": "reconcile_cash_call",
    "arguments": {
      "transaction_id": "INV-2026-042",
      "gross_amount": 1500000.0,
      "currency": "USD",
      "vat_rate": 7.5,
      "wht_rate": 5.0
    }
  }
}

Response Frame with Cryptographic Audit Signature

{
  "jsonrpc": "2.0",
  "id": 101,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"transaction_id\": \"INV-2026-042\",\n  \"gross_amount\": 1500000.0,\n  \"computed_vat\": 112500.0,\n  \"computed_wht\": 75000.0,\n  \"net_payable\": 1537500.0,\n  \"reconciliation_status\": \"BALANCED\"\n}"
      }
    ],
    "isError": false,
    "metadata": {
      "tool": "reconcile_cash_call",
      "tokens": 42
    }
  }
}

---

👨‍💻 Author & Engineering Standards

• Engineer: Jerry Nabasu (jerrynabasu@gmail.com)
• Standards: Zero-Mock Policy, 100% automated test coverage, strict privacy anonymization.
• License: MIT