MCP-Mesh 🌐🔒

Universal Model Context Protocol (MCP) Router & Gateway Adapter with ISO/IEC 42001 AI Governance & Modern Web Dashboard

MCP-Mesh is an enterprise-grade AI Gateway, Protocol Adapter, and Smart Tool Router built for the Model Context Protocol (MCP). It bridges external legacy & cloud infrastructures (OpenAPI/REST, GraphQL, AWS Lambda) with LLM Agents, enforcing ISO/IEC 42001 AI Governance, Role-Based Access Control (RBAC), Automatic PII Redaction, Semantic Tool Routing, and a Modern React-based Web Dashboard UI.

---

🌟 Key Features

• 📊 Modern Web Dashboard UI: High-performance React 18 interface with live telemetry monitoring, trace inspection, interactive role preview, adapter management, and instant Light/Dark mode.
• 🌐 Universal Protocol Adapters: Dynamic schema ingestion for OpenAPI (Swagger 3.0), GraphQL queries, and AWS Lambda functions—converting them into instantly discoverable MCP tools on the fly.
• 🛡️ ISO/IEC 42001 AI Governance: Automated AI System Risk Assessment engine evaluating operation severity (Low, Medium, High, Critical), parameter payload complexity, and prompt/SQL injection protection.
• 🧠 Smart Semantic Tool Router: In-memory TF-IDF & Cosine Similarity vector search index that dynamically exposes only top relevant tools to the LLM based on query context, preventing context window bloat.
• 🔒 Enterprise Security & PII Redaction: Automatic real-time detection and masking of emails, credit cards, SSNs, phone numbers, and API credentials in both request arguments and response payloads ([REDACTED]).
• 🔑 OAuth2 JWT & RBAC Enforcement: Role-Based Access Control matrix (admin, developer, analyst, guest) restricting tool discovery and execution based on agent identity.
• ⚡ Telemetry, Resilience & Replay: Complete JSON-RPC execution audit logging, circuit breaking for downstream service isolation, and deterministic trace replay (/admin/telemetry/replay/{trace_id}).
• 🔌 Dual Transport Modes: Native support for both stdio (for local IDEs like Antigravity & Claude Desktop) and HTTP REST/SSE (for distributed microservices).

---

📐 System Architecture

                                    +------------------------------+
                                    |    LLM Agent / Desktop IDE   |
                                    +------------------------------+
                                                   |
                                            (JSON-RPC 2.0)
                                                   |
                                                   v
+--------------------------------------------------------------------------------------------------+
|                                         MCP-MESH GATEWAY                                         |
|                                                                                                  |
|   +-------------------+    +----------------------+    +-------------------+    +--------------+ |
|   |  JWT & Agent Auth | -> |  RBAC Scoping Engine | -> | ISO 42001 Engine  | -> |  PII Masker  | |
|   +-------------------+    +----------------------+    +-------------------+    +--------------+ |
|                                                                                                  |
|   +------------------------------------------------------------------------------------------+   |
|   |                 Web Dashboard UI (http://localhost:8000/dashboard)                      |   |
|   +------------------------------------------------------------------------------------------+   |
|                                                                                                  |
|                                     +--------------------------+                                 |
|                                     | Smart Semantic Router    |                                 |
|                                     | (TF-IDF Vector Index)    |                                 |
|                                     +--------------------------+                                 |
|                                                  |                                               |
|                                     +--------------------------+                                 |
|                                     | Central Tool Registry    |                                 |
|                                     +--------------------------+                                 |
|                                                  |                                               |
+--------------------------------------------------|-----------------------------------------------+
                                                   |
                        +--------------------------+--------------------------+
                        |                          |                          |
                        v                          v                          v
             +--------------------+      +-------------------+      +-------------------+
             |  OpenAPI Adapter   |      |  GraphQL Adapter  |      |   Lambda Adapter  |
             +--------------------+      +-------------------+      +-------------------+
                        |                          |                          |
                        v                          v                          v
                [ Upstream REST ]          [ Upstream GraphQL ]        [ AWS Lambda Functions ]

---

💻 Web Dashboard UI Overview

Access the live dashboard at http://localhost:8000/dashboard (or http://localhost:8000/).

Features:

1. 📡 Telemetry & ISO 42001 Audit Stream: Live execution log with status filter pills (ALL, SUCCESS, BLOCKED_RBAC, BLOCKED_ISO42001), JSON payload inspector, and 1-click Trace Replay.
2. 🔌 Dynamic Adapters Hub: Manage connected OpenAPI, GraphQL, and AWS Lambda adapters with interactive modal registration forms.
3. 🧠 Smart Router & Security Playground: Test bench to simulate LLM user prompts and inspect tool rankings and role permissions live.
4. 🌓 Light / Dark Mode System: Custom glassmorphism design with seamless theme toggling.

---

📦 Installation & Setup

Prerequisites

• Python 3.10 or higher

Install from Source

git clone https://github.com/mcp-mesh/mcp-mesh.git
cd mcp-mesh
pip install -e .

---

🚀 Quick Start & Launch Modes

Mode 1: HTTP REST Server & Web Dashboard Mode

Launch the Gateway server and Web UI:

# Option A: Using CLI command (if installed via pip install -e .)
mcp-mesh start --host 0.0.0.0 --port 8000

# Option B: Direct Python execution
python -m uvicorn mcp_mesh.api.app:app --host 0.0.0.0 --port 8000 --reload

👉 Open browser at http://localhost:8000/dashboard.

Mode 2: Local Stdio Transport Mode

Run in stdio mode for local IDE integration (Antigravity IDE, Claude Desktop):

mcp-mesh stdio
# OR
python -m mcp_mesh.cli stdio

---

🧪 Live Interactive Demo Script

Run the automated live demonstration script to populate telemetry traces and test adapter registration:

python run_example.py

This script automatically:

1. Registers the Swagger Petstore OpenAPI endpoints into MCP-Mesh as tools.
2. Performs contextual tool discovery (tools/list) using the Smart Vector Router.
3. Executes a tool call with customer data and displays real-time PII Redaction.
4. Triggers an ISO/IEC 42001 Risk Interception blocking a delete operation.

---

⚙️ Configuration Reference

Configure MCP-Mesh via environment variables (or .env file):

Variable	Default Value	Description
MCP_MESH_PORT	8000	Gateway HTTP server port
MCP_MESH_JWT_SECRET_KEY	mcp-mesh-super-secret-key...	JWT token signing key
MCP_MESH_ENABLE_AUTH	True	Enforce JWT token authentication
MCP_MESH_ISO42001_COMPLIANCE_MODE	True	Enable ISO 42001 risk evaluation & policy enforcement
MCP_MESH_ENABLE_PII_MASKING	True	Enable automatic PII masking in inputs/outputs
MCP_MESH_PII_REDACTION_STRING	[REDACTED]	Text label substituted for PII data
MCP_MESH_MAX_TOOLS_PER_PROMPT	15	Max tools returned by smart router per query
MCP_MESH_DATABASE_URL	sqlite+aiosqlite:///./mcp_mesh.db	Telemetry database connection URI

---

📖 Protocol & API Usage Examples

1. Dynamic OpenAPI Adapter Registration

Register a live OpenAPI endpoint or specification:

POST /admin/adapters/openapi
Content-Type: application/json

{
  "name": "petstore",
  "spec_source": "https://petstore.swagger.io/v2/swagger.json"
}

2. Listing Tools with Contextual Semantic Filtering

Request tools relevant to a specific user prompt context:

POST /mcp
Content-Type: application/json
X-Query-Prompt: "I need to look up pet order details and inventory"
Authorization: Bearer <YOUR_JWT_TOKEN>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

3. Calling an MCP Tool with Governance & PII Masking

Execute a tool through the MCP-Mesh gateway:

POST /mcp
Content-Type: application/json
Authorization: Bearer <YOUR_JWT_TOKEN>

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "petstore_getOrderById",
    "arguments": {
      "orderId": 5
    }
  }
}

---

🔒 Security & AI Governance Details

Role-Based Access Control (RBAC)

Role	Permitted Actions / Tool Patterns
admin	Full access to all tools (*)
developer	read_*, write_*, list_*, get_*, execute_*
analyst	Read-only operations (read_*, list_*, get_*, query_*, search_*)
guest	Discovery only (list_*, search_*)

ISO/IEC 42001 Risk Levels

• LOW: Read-only operations and non-mutating queries.
• MEDIUM: Low-impact state modifications (drafting, local cache updates).
• HIGH: Destructive updates or complex writes (restricted for untrusted roles).
• CRITICAL: High-risk keywords (delete, drop, truncate, shell, exec) requiring admin or supervisor roles.

---

🧪 Running Unit Tests

Execute the comprehensive test suite:

python -m unittest discover -s tests

---

📄 License

This project is licensed under the MIT License.