nexus-mcp/documentation/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 nexus-mcp/README.md for the full tool reference and NEXUS work item tracking