Master MCP Server Setup & Deployment Guide

The Systemores Master MCP Server (from the systemores-mcp-clean distribution) provides Model Context Protocol (MCP) access for psychometric stress-testing, persona evaluation, behavioral compliance auditing, multi-agent graph topological verification, synthetic population generation, and OpenTelemetry trace analysis for autonomous AI agents.

Powered by the Systemores Core behavioral engine (Murray Needs-Press model) and the EthosNeo / EthosSim psychometric framework, the Master MCP Server supports both local stdio execution and cloud Streamable HTTP transport (compliant with the MCP 2026-07-28 specification).

1. Quick Start & Installation

Clone or unpack the systemores-mcp-clean repository and run the setup sequence:

# 1. Install dependencies
npm install

# 2. Copy environment template and fill in your keys
cp .env.example .env

# 3. Build TypeScript output
npm run build

# 4. Run automated smoke tests (32 assertions across 8 test suites)
node smoke-test.mjs

# 5a. Run locally (stdio — for Claude Desktop, Cursor, VS Code)
npm start

# 5b. Run as a hosted web service (Streamable HTTP)
npm run start:http

Complete 11-Tool Suite Summary Matrix

The Master MCP Server exposes 11 standardized diagnostic, multi-agent, and runtime defense tools:

Tool Name	Engine / Architecture	Primary Use Case
systemores_stress_test_agent	Systemores Core API + Gemini	Adversarial Press testing & persona stability under manipulation.
systemores_evaluate_drift	Systemores Core API + Gemini	Multi-turn behavioral drift & semantic decay evaluation.
systemores_assess_bias	Systemores Core API + Statutory Rules	Statutory compliance alignment (EEOC, ECOA, COPPA, Fair Housing).
systemores_measure_drag	Latency & Token Density Engine	Cognitive efficiency, response latency, and throughput scoring.
systemores_audit_tool_integrity	Offline JSON Schema Validator	Tool schema structural integrity, privilege overreach & injection audit.
systemores_audit_agent_graph	DFS Topological Scanner	Multi-agent DAG cycle loop detection & privilege escalation tracing.
systemores_generate_cohort	EthosSim Engine	Synthetic user population cohort generation (adversarial, noisy, demographic).
systemores_inject_environment_fault	Chaos Proxy Policy Middleware	Runtime fault injection (HTTP 429 rate limit, 500 server error, timeout, 401, malformed JSON).
systemores_analyze_trace_telemetry	OpenTelemetry Parser	Token cost burn trap (> $2.50 threshold) & runtime loop deadlock detection.
systemores_export_dossier	Multi-Framework Reporter	Formal audit dossiers (EU AI Act EU 2024/1689, NIST AI RMF 1.0, EEOC/ECOA, SOC 2).
systemores_audit_turn_live	TypeSafe Jev + Gemini	Sub-300ms inline circuit breaker (DISPATCH, INTERCEPT, QUARANTINE, STRIP_TOOL) & self-healing logs.

2. Environment Configuration Reference

Configure your keys in .env (or set environment variables in your deployment runtime):

Variable Name	Required	Description / Default Host Endpoint
AUDIT_API_KEY	Yes (Live Ethos Suite)	Authenticates against EthosSim and EthosNeo psychometric services.
ETHOS_SIM_API_URL	No	Defaults to `https://sim.systemores.com/api/v1` for simulation & cohort generation.
ETHOS_VECTOR_API_URL	No	Defaults to `https://neo.systemores.com/api/v1` for human & persona profile queries.
SYSTEMORES_CORE_API_KEY	Yes (Live Needs-Press)	Systemores core API key for 21-dimension psychometrics (`https://api.systemores.com/api/v1/score`).
GEMINI_API_KEY	Yes (Gemini Parsing)	Google Gemini API key used by semantic adjective extraction.
GEMINI_MODEL	No	Defaults to `gemini-3.5-flash-lite` (fast & economical) or `gemini-3.8-flash` (advanced reasoning).
TYPESAFE_API_KEY	No (Optional)	Enables sub-300ms inline circuit breaker evaluations (`systemores_audit_turn_live`) via TypeSafe Jev System One.
PORT	No	Express HTTP server port. Defaults to `3001`.

🛡️ Graceful Fallback Notice: If any API key (AUDIT_API_KEY, SYSTEMORES_CORE_API_KEY, GEMINI_API_KEY) is missing or a service endpoint is unreachable, the auditor automatically emits a clear notice to stderr and uses local, deterministic calculations (30-facet model and Murray Needs-Press engine). This ensures offline development, CI/CD gates, and local evaluation remain 100% operational without runtime crashes.

3. Client Deployment Configurations

1. Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "systemores-agent-auditor": {
      "command": "node",
      "args": [
        "/absolute/path/to/systemores-mcp-clean/build/index.js"
      ],
      "env": {
        "AUDIT_API_KEY": "your_audit_api_key_here",
        "SYSTEMORES_CORE_API_KEY": "your_systemores_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here"
      }
    }
  }
}

2. Cursor IDE (`.cursor/mcp.json`)

{
  "mcpServers": {
    "systemores-agent-auditor": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/systemores-mcp-clean/build/index.js"
      ],
      "env": {
        "AUDIT_API_KEY": "your_audit_api_key_here",
        "SYSTEMORES_CORE_API_KEY": "your_systemores_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here"
      }
    }
  }
}

3. Remote Streamable HTTP Deployment

For remote client deployments, start the HTTP server (npm run start:http or Docker container) and point client MCP configurations to the /mcp endpoint:

{
  "mcpServers": {
    "systemores-agent-auditor": {
      "url": "https://mcp.yourdomain.com/mcp"
    }
  }
}

4. Verification & Automated Testing

To verify the installation and confirm that all 11 tools, schema definitions, and psychometric engines are working as expected:

npm run build
node smoke-test.mjs

All 37 test assertions across all 9 test sections should pass cleanly.

5. Licensing & Commercial Support

This software is commercially licensed by Systemores. Contact systemores.com for production keys, custom enterprise deployment gates, and managed cloud trial tokens.

← View Integration Workflows ← Back to Audit Playground