nexus-mcp/DEMO_GUIDE.md

Nexus-MCP — Demo and Setup Guide

Sharded enterprise integration MCP server for Active Directory, Entra ID, Workday, BMC Helix, Lansweeper, Intune, FedEx, and cross-system drift auditing.

All test scripts must be run from the nexus-mcp/ directory.

---

Prerequisites

• Python 3.11 or newer
• Git
• PowerShell (Windows) or bash (Linux/macOS)
• Access to corporate systems (AD, Entra, Workday) — or enable mock mode (no credentials needed)

---

Installation

1. Navigate to the server directory

cd /path/to/mcp_servers/nexus-mcp

2. Create and activate a virtual environment

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Windows (bash/Git Bash):

python -m venv .venv
source .venv/Scripts/activate

Linux/macOS:

python -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -e .

Installs nexus-mcp in editable mode with all required packages (mcp, httpx, python-dotenv, ldap3, msal, etc.).

---

Configuration

1. Create .env file

cp .env.example .env

2. Choose your mode

Option A: Mock mode (no credentials needed)

Good for development, testing shards, and exploring drift scenarios.

USE_MOCK=true

ENABLE_IDENTITY=true
ENABLE_WORKDAY=true
ENABLE_AUDIT=true
ENABLE_ITSM=false
ENABLE_ASSETS=false
ENABLE_LOGISTICS=false

AUDIT_LOGGING_ENABLED=true
AUDIT_LOG_FILE=./logs/nexus_audit.jsonl
AUDIT_LOG_STDERR=true

Option B: Live mode (production credentials)

Requires actual service accounts and API credentials. Enable only the shards where credentials are available.

USE_MOCK=false

ENABLE_IDENTITY=true
ENABLE_WORKDAY=false    # Set true when credentials available
ENABLE_AUDIT=true
ENABLE_ITSM=false
ENABLE_ASSETS=false
ENABLE_LOGISTICS=false

# Active Directory
AD_SERVER=ldap://your-dc.company.com
AD_PORT=389
AD_BASE_DN=DC=company,DC=com
AD_USER=CN=svc_nexus,OU=Service Accounts,DC=company,DC=com
AD_PASSWORD=your_password
AD_USE_SSL=false

# Microsoft Entra ID (Azure AD)
ENTRA_TENANT_ID=your_tenant_id
ENTRA_CLIENT_ID=your_client_id
ENTRA_CLIENT_SECRET=your_client_secret

Your .env file is never committed to git.

---

Running the server

python src/main.py

Expected startup output (mock mode, default shards):

[nexus] ✅ identity shard loaded
[nexus] ✅ workday shard loaded
[nexus] ✅ audit shard loaded
[nexus] ⏸  itsm shard disabled (ENABLE_ITSM != true)
[nexus] ⏸  assets shard disabled (ENABLE_ASSETS != true)
[nexus] ⏸  logistics shard disabled (ENABLE_LOGISTICS != true)
[nexus] 🔒 SOC 2 audit middleware active → ./logs/nexus_audit.jsonl

The server runs on stdio transport and waits for MCP protocol messages.

---

Claude Desktop integration

Add this block to your Claude Desktop config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["src/main.py"],
      "cwd": "C:/Users/your-username/repos/mcp_servers/nexus-mcp",
      "env": {
        "USE_MOCK": "true"
      }
    }
  }
}

Restart Claude Desktop. The Nexus tools will appear in the tool picker.

---

Feature flag reference

Flag	Shard	Systems	Default
ENABLE_IDENTITY	identity.py	Active Directory + Entra ID	true
ENABLE_WORKDAY	workday.py	Workday HCM	true
ENABLE_AUDIT	audit.py	Cross-system drift	true
ENABLE_ITSM	itsm.py	BMC Helix	false
ENABLE_ASSETS	assets.py	Lansweeper + Intune	false
ENABLE_LOGISTICS	logistics.py	FedEx	false

Set a flag to false (or omit it) to put that shard in holding pattern. The server will start successfully and skip those tools.

---

Quick start — demo scripts

All scripts run from the nexus-mcp/ directory against mock data.

Audit tools demonstration

python test_client.py

Shows all 4 audit scan tools executing with severity classification and mismatch summaries.

Expected: 6 total mismatches across 9 employee records.

Tool catalog browser

python list_tools.py

Shows the complete tool inventory (50 tools), organized by shard, with descriptions from docstrings.

MCP protocol simulation

python test_mcp_protocol.py

Simulates the full MCP handshake: protocol negotiation → tools/list discovery → tools/call invocation → JSON response. Useful for verifying Claude Desktop compatibility.

---

Test suite

Run from the nexus-mcp/ directory:

# Full suite
pytest tests/ -v

# Specific modules
pytest tests/identity_tests/ -v
pytest tests/workday_tests/ -v

# With coverage
pytest tests/ --cov=lib --cov=src --cov-report=term-missing

# Audit integration tests only
pytest tests/workday_tests/ tests/integration_test_audit_shard.py -v

Expected baseline: 10/10 passing in ~0.6s.

See nexus-mcp/TEST_VALIDATION_REPORT.md for full results and MCP protocol compliance details.

---

Mock data and drift scenarios

Mock data is defined in lib/mock_data.py. Pre-seeded mismatches cover all severity levels:

Employee	Mismatch	Severity	Detected by
Terminated worker	Active in Workday as terminated, AD account still enabled	HIGH	scan_status_reconciliation
Bob Martinez	Title differs — AD: "Sr. Software Engineer" vs Workday: "Software Engineer"	MEDIUM	scan_job_title_drift
Carol Chen	Department differs — Workday: "Product Management" vs AD: "Engineering"	MEDIUM	scan_department_mismatches
3 employees	AD display name doesn't align with legal/preferred name in Workday	LOW	scan_name_variance_mismatches

Employee records: 9 (EMP001–EMP777) | Total pre-seeded mismatches: 6

Try the audit tools in Claude chat with Nexus-MCP active:

"Scan for terminated workers still active in AD"
"Run a job title drift scan"
"Show me all stale AD accounts"
"Run audit statistics"

---

SOC 2 audit logging

Every tool call is logged to logs/nexus_audit.jsonl (one JSON object per line, automatically redacted).

Each entry contains:

• event_id — UUID v4 for correlation
• timestamp — ISO 8601 UTC
• tool — MCP tool name
• shard — identity | workday | audit | etc.
• action_category — READ | AUDIT | REPORT
• args_summary — call arguments with passwords/tokens redacted
• mock_mode — true/false
• status — success | error
• latency_ms — execution time

Query the audit log directly using the built-in tools:

"Show me the last 50 audit log entries"   → nexus_audit_recent
"Give me audit statistics"                → nexus_audit_stats

---

Troubleshooting

Server won't start

• Check Python version: python --version (must be 3.11+)
• Verify the venv is active ((.venv) should appear in your prompt)
• Verify dependencies: pip list | grep mcp

Shard not loading

• Check the feature flag in .env: ENABLE_IDENTITY=true
• Look for error messages in the startup output
• Verify the shard file exists: ls src/shards/identity.py

Credentials not working (live mode)

• Test AD connectivity: python -c "import ldap3; print(ldap3.__version__)"
• Verify the service account can bind to LDAP
• Check firewall rules for on-prem AD

Audit log not writing

• Check permissions on the logs/ directory
• Verify AUDIT_LOGGING_ENABLED=true in .env

---

Development workflow

Adding a tool to an existing shard

1. Edit the shard file (e.g. src/shards/identity.py)
2. Add the tool function inside register(mcp) using the @mcp.tool() decorator
3. Restart the server and test in Claude Desktop

Creating a new shard

1. Copy an existing shard as a template: cp src/shards/identity.py src/shards/my_system.py

2. Implement register(mcp) with your tools

3. Add the shard to src/main.py:

   if _enabled("MY_SYSTEM"):
       my_system.register(mcp)
   

4. Add the flag to .env.example: ENABLE_MY_SYSTEM=false

Switching between mock and live mode

Change USE_MOCK in .env and restart — no code changes needed:

USE_MOCK=false
python src/main.py

---

Next steps

1. Run python test_client.py to verify audit tools work in mock mode
2. Explore the pre-seeded drift scenarios using audit tools in Claude chat
3. Populate .env with live credentials for available systems
4. Enable additional shards as credentials are provisioned
5. Review README.md for the full tool reference and NEXUS work item tracking