Workflow Intelligence MCP
Connects to n8n workflow engines to retrieve workflow execution histories and failure context, supporting exception investigation, root-cause analysis, and recovery recommendations for automated pipelines.
Connects to Temporal workflow engines to retrieve workflow execution histories and failure context, supporting exception investigation, root-cause analysis, and recovery recommendations for automated pipelines.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Workflow Intelligence MCP
Executive Summary
Enterprise businesses rely on complex webs of workflow engines, ERP systems, databases, and manual approval chains. While workflow engines like Temporal and n8n excel at executing predefined sequences, organizations face critical operational hurdles:
Invisible Inefficiencies: Undetected approval queues, unnecessary activity repetitions, and human handoff delays.
Fragile Exception Handling: Workflows that halt abruptly due to minor schema drifts, missing vendor records, or data mismatches, requiring tedious manual triage.
Unexplained Metric Deviations: Operational costs spike or SLA cycle times inflate, but operational dashboards only show what happened, not why it happened or which source records caused it.
Workflow Intelligence MCP is a specialized Model Context Protocol server that sits alongside workflow engines as a dedicated process intelligence, exception reasoning, and business decision layer.
┌────────────────────────────────────────────────────────────────────────┐
│ WORKFLOW INTELLIGENCE MCP │
├──────────────────────────┬─────────────────────────┬───────────────────┤
│ 1. Process Discovery │ 2. Exception Resolver │ 3. Decision Intel │
│ Engine (`process_`) │ (`exception_`) │ (`decision_`) │
├──────────────────────────┼─────────────────────────┼───────────────────┤
│ • Event log ingestion │ • Exception triage │ • KPI deviation │
│ • PM4Py reconstruction │ • Context retrieval │ root-cause │
│ • Bottleneck detection │ • Recovery suggestions │ • DuckDB analysis │
│ • Automation scoring │ • Escalation routing │ • Evidence briefs │
└──────────────────────────┴─────────────────────────┴───────────────────┘Related MCP server: commerce-ops-harness
Core Differentiators
Intelligence, Not Execution: Complements existing workflow orchestrators (Temporal, n8n) rather than replacing them.
Deterministic Computing: All metrics, aggregations, process graphs, and numerical KPIs are computed using deterministic code (PM4Py, DuckDB, Pandas, SQL). Reports, narratives, and recommendations are formulated deterministically from verified numbers—eliminating LLM hallucinations in analytical calculations.
Verifiable Data Provenance: Every insight, recommendation, and brief generated by the server links explicitly to underlying dataset identifiers, file SHA-256 digests, and deterministic query logic.
System Architecture
The server adheres to a strict, modular layered architecture where MCP handlers remain thin transport layers that delegate directly to isolated application services and adapters.
flowchart TD
Client["MCP Clients\n(Claude Desktop / Cursor / Custom Agents)"]
subgraph MCP_Protocol ["MCP Protocol Layer"]
Transport["FastMCP Server\n(STDIO / Streamable HTTP)"]
Handlers["Thin Tool & Resource Handlers"]
end
subgraph Validation ["Validation & Security Layer"]
Pydantic["Pydantic V2 Schemas\n(Input / Output Contracts)"]
AuthZ["Authorization & Access Policy"]
end
subgraph Services ["Application Services"]
Dependencies["ServiceContainer\n(Dependency Injection)"]
PS["ProcessService\n(Process Mining & Reconstruction)"]
ES["ExceptionService\n(Triage & Root Cause Resolution)"]
DS["DecisionService\n(KPI & Decision Briefs)"]
AS["AnalyticsService\n(DuckDB Query Engine)"]
EVS["EvidenceService\n(Record Matching & Provenance)"]
end
subgraph Adapters ["Integration Adapters"]
PMAdapter["PM4Py Adapter"]
DuckAdapter["DuckDB / SQL Adapter"]
WorkflowAdapter["Temporal / n8n Connectors"]
FileAdapter["CSV / JSON / Parquet Loaders"]
end
subgraph Storage ["Persistence & State"]
PG[(PostgreSQL State)]
Duck[(In-Memory / Local DuckDB)]
end
Client <--> Transport
Transport --> Handlers
Handlers --> Pydantic
Pydantic --> AuthZ
AuthZ --> Dependencies
Dependencies --> Services
PS --> PMAdapter
ES --> WorkflowAdapter
ES --> EVS
DS --> AS
AS --> DuckAdapter
DuckAdapter --> Duck
WorkflowAdapter --> PG
PMAdapter --> FileAdapterThe Three Core MCP Tools
1. Process Discovery Engine (process_*)
Ingests operational event logs, reconstructs execution paths using process mining, identifies systemic bottlenecks, and calculates objective automation suitability scores.
Tool Name | Parameters | Output Schema | Purpose |
|
|
| Ingests event logs, computes transition matrices, case statistics, and path variants. |
|
|
| Detects abnormal queue durations, repeated task loops, and departmental handoff delays. |
|
|
| Evaluates repetitive activities against volume, variance, and manual touchpoints to rank automation targets. |
Example Invocations & Output
// Tool: process_identify_bottlenecks
{
"source_uri": "sample-data/procurement_events.csv",
"threshold_std_dev": 2.0
}// Response
{
"total_cases_analyzed": 1420,
"bottlenecks": [
{
"stage": "Finance Approval -> Vendor Selection",
"avg_duration_hours": 74.2,
"baseline_duration_hours": 12.0,
"deviation_score": 3.8,
"primary_cause": "Pending manual budget verification",
"affected_case_count": 312
}
],
"recommendations": [
"Introduce automated budget pre-checks for purchase requisitions under $5,000."
]
}2. Workflow Exception Resolver (exception_*)
Investigates execution failures across automated pipelines, fetches contextual records from databases or workflow histories, reconciles discrepancies, and determines safe recovery or escalation paths.
Tool Name | Parameters | Output Schema | Purpose |
|
|
| Classifies failures (validation, API timeout, record mismatch) and gathers case history. |
|
|
| Produces actionable remediation steps (e.g., entity deduplication, automated retry, or manual correction). |
|
|
| Routes unresolvable or high-risk exceptions to authorized human operators with full audit context. |
Example Invocation & Output
// Tool: exception_investigate_workflow
{
"case_id": "PO-10042",
"workflow_type": "purchase_order_creation",
"failure_payload": {
"error_code": "VENDOR_RECORD_MISMATCH",
"submitted_name": "ABC Logistics LLC",
"tax_identifier": "TX-992140"
}
}// Response
{
"investigation_id": "INV-8831",
"case_id": "PO-10042",
"root_cause_category": "Data Discrepancy",
"explanation": "Submitted vendor 'ABC Logistics LLC' matches registered entity 'ABC Logistics Global Inc' with 98% confidence on tax ID 'TX-992140'.",
"matched_records": [
{ "entity_id": "VEND-00412", "registered_name": "ABC Logistics Global Inc" }
],
"can_auto_resolve": true,
"recommended_action": "Remap vendor_id to VEND-00412 and resume workflow step: dispatch_po."
}3. Business Decision Intelligence (decision_*)
Executes high-performance analytical queries using embedded DuckDB to evaluate business KPI shifts, identify underlying contributing segments, and produce verifiable decision briefs.
Tool Name | Parameters | Output Schema | Purpose |
|
|
| Evaluates deterministic KPI variance across periods over any CSV/Parquet dataset with zero hardcoding. |
|
|
| Explains variance drivers with dynamic dimension inference and statistical significance indicators. |
|
|
| Synthesizes verified numbers, root causes, and recommended actions into an executive-ready brief with SHA-256 provenance links. |
Example Output: Structured Decision Brief
# Operational Decision Brief: Q3 Procurement Cost Inflation
**Generated:** 2026-11-12 | **Target:** Operations & Procurement Leadership
### Executive Summary
Procurement processing costs experienced an increase of **+28.4%** ($68,000 vs. $52,000 baseline).
### Key Contributing Drivers (Verified via DuckDB)
- **Emergency Expedited Shipping:** Accounted for **64%** of cost increase across 32 purchase orders.
- **Supplier Off-Contract Orders:** Department 'Engineering Hardware' placed 41% of requests outside preferred vendor catalogs.
### Supporting Evidence & Provenance
- Dataset: `sample-data/procurement_costs.csv`
- Records Evaluated: 1,420 transactions
- Verified Calculation: `AVG(cost_per_order)` shifted from $49.52 to $65.21 ($p < 0.01$).
### Recommended Interventions
1. Implement vendor catalog constraints for requisitions exceeding $2,500.
2. Automate lead-time notifications to eliminate rush-order delivery fees.MCP Resources & Prompts
In addition to tools, Workflow Intelligence MCP exposes standardized protocol primitives:
MCP Resources
workflow://process-maps/{process_name}: Dynamic Directly-Follows Graphs resolved from any registered event log insample-data/.workflow://exceptions/active: Real-time index of open workflow exceptions and priority queues fromExceptionRepository.workflow://metrics/kpi-definitions: Deterministic SQL definitions and calculation formulas.workflow://audit/recent: Recent immutable audit trail entries capturing system decisions and escalations.
MCP Prompts
process_bottleneck_review: Pre-structured prompt for comprehensive operational workflow analysis.exception_triage_session: Interactive step-by-step assistant for reconciling ambiguous case failures.management_decision_brief: Standardized template for generating executive operational reports.
End-to-End Walkthrough: Procurement Lifecycle
The server demonstrates its integrated intelligence loop through a single end-to-end procurement process:
Step 1: Discover
Event Logs Ingested ──► PM4Py detects 74-hour approval queues in Finance.
Score ranking identifies 'Requisition Approval' as #1 automation target.
│
▼
Step 2: Resolve
Execution Halts ──► A high-value PO fails at vendor dispatch.
Exception service triages fuzzy vendor mismatch, retrieves tax record,
and safely auto-heals the workflow with full audit logging.
│
▼
Step 3: Decide
Quarterly Review ──► Executive asks: 'Why did procurement costs spike 28%?'
Decision Intelligence queries transaction logs, attributes the increase
to rush delivery fees caused by the upstream approval bottleneck,
and drafts an evidence-backed decision brief.Installation & Quickstart
Prerequisites
Python
>= 3.12Docker & Docker Compose (Optional, for containerized deployment)
1. Local Setup
# Clone the repository
git clone https://github.com/coder-aadii/Workflow-Intelligence-MCP.git
cd Workflow-Intelligence-MCP
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install package and dependencies in editable mode
pip install -e ".[dev]"2. Environment Configuration
cp .env.example .env
# Edit .env to set your database or analytical paths3. Running the Server
Option A: Standard I/O (STDIO) — Default for local desktop agents
python -m workflow_intelligence.server --transport stdioOption B: Unified Dual-Transport (Streamable HTTP + Legacy SSE) — Recommended for Docker
python -m workflow_intelligence.server --transport unified --port 8000This serves:
Streamable HTTP endpoint:
POST http://127.0.0.1:8000/mcpLegacy SSE endpoint:
GET http://127.0.0.1:8000/sseHealth check probe:
GET http://127.0.0.1:8000/healthReadiness probe:
GET http://127.0.0.1:8000/ready
Option C: Standalone Streamable HTTP
python -m workflow_intelligence.server --transport streamable-http --port 8000Option D: Standalone SSE
python -m workflow_intelligence.server --transport sse --port 8000MCP Client Configuration
Claude Desktop (STDIO)
Add the server definition to claude_desktop_config.json:
{
"mcpServers": {
"workflow-intelligence": {
"command": "/path/to/Workflow-Intelligence-MCP/.venv/bin/python",
"args": ["-m", "workflow_intelligence.server", "--transport", "stdio"],
"env": {
"WORKFLOW_ENV": "development",
"DATABASE_URL": "postgresql+asyncpg://postgres:postgres@localhost:5432/workflow_intelligence"
}
}
}
}Streamable HTTP Client (Claude Desktop / Remote Agent)
When running over the network in production with bearer token authentication:
{
"mcpServers": {
"workflow-intelligence-remote": {
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer your-secure-mcp-auth-token"
}
}
}
}Legacy SSE Client
{
"mcpServers": {
"workflow-intelligence-sse": {
"url": "http://127.0.0.1:8000/sse",
"headers": {
"Authorization": "Bearer your-secure-mcp-auth-token"
}
}
}
}Cursor IDE Configuration
In Cursor's Features > MCP Servers settings:
Name:
workflow-intelligenceType:
commandCommand:
python -m workflow_intelligence.server --transport stdio
Environment Variables Reference
Variable | Description | Default |
| Application environment ( |
|
| MCP transport mechanism ( |
|
| Host address for network transports |
|
| Port for HTTP transports |
|
| Bearer token for network endpoints (mandatory in production) |
|
| Gateway indicator; in production, |
|
| Comma-separated allowlist of accessible data directories |
|
| Maximum allowable file size before ingestion rejection |
|
| Timeout for process mining with process-isolated termination |
|
| Timeout for analytical DuckDB queries in milliseconds |
|
| PostgreSQL asyncpg connection string |
|
| Path to persistent DuckDB file (or |
|
| Redis URL for workflow caching |
|
| Structured logging verbosity ( |
|
Real-World Dataset Benchmarks
Workflow-Intelligence-MCP was validated against high-volume, real-world enterprise datasets:
1. BPIC19 Flat Event Log (local/BPIC19_flat.csv)
Scale: 1,595,923 events | 251,734 cases | 42 unique activities
Execution Time: 332.73s (~5.5 min)
Peak RAM: 1,260.51 MB (~1.26 GB)
Results: Discovered 11,973 variants and 498 directly-follows transitions.
Resource Safety: Bounded execution via OS process isolation guarantees that timed-out workloads cannot consume unbounded CPU or leak memory.
2. Insurance Claims Event Log (local/Insurance_claims_event_log.csv)
Scale: 180,000 events | 30,000 cases | 6 unique activities
Execution Time: 55.98s
Peak RAM: 291.09 MB
Operational Bottleneck Detected:
First Notification of Loss (FNOL) -> Assign Claim(avg duration 360.25 hours / 15 days, impacting 29,807 claims / 99.36%).Automation Potential: FNOL identified as #1 candidate for RPA/automated ingestion.
DuckDB Analytical Validation: Aggregated claim amounts across Collision ($5,498.07 avg), Comprehensive ($5,502.13 avg), and Liability ($5,495.59 avg) with zero procurement assumptions.
Benchmark Reproduction: Benchmarks can be executed locally against large event logs in
local/usingpython3 scripts/regression_test.py.
Operations & Disaster Recovery Runbook
Health Probes
Liveness Probe:
GET http://127.0.0.1:8000/health-> returns{"status": "healthy"}Readiness Probe:
GET http://127.0.0.1:8000/ready-> validates DB connectivity and returns{"status": "ready"}
PostgreSQL Backup & Recovery
# Backup database to SQL dump
docker compose exec -T postgres pg_dump -U postgres workflow_intelligence > wimcp_backup_$(date +%Y%m%d_%H%M%S).sql
# Restore database from backup
docker compose exec -T postgres psql -U postgres workflow_intelligence < wimcp_backup_20261116.sqlRollback Procedure
If a deployment fails, rollback safely without data loss:
# Graceful stop
docker compose stop workflow-intelligence-mcp
# Roll back code to pre-hardening tag/checkpoint
git checkout checkpoint-pre-hardening
# Rebuild and start container
docker compose up -d --buildRepository Structure
workflow-intelligence-mcp/
├── src/
│ └── workflow_intelligence/
│ ├── server.py # FastMCP server entrypoint & lifecycle
│ ├── config.py # Pydantic Settings configuration
│ ├── dependencies.py # Dependency injection container
│ │
│ ├── tools/ # Thin MCP tool endpoints
│ │ ├── process_discovery.py # process_* endpoints
│ │ ├── exception_resolver.py # exception_* endpoints
│ │ └── decision_intelligence.py# decision_* endpoints
│ │
│ ├── resources/ # MCP Resources (process maps, metrics)
│ ├── prompts/ # MCP Prompt templates
│ │
│ ├── services/ # Core business logic
│ │ ├── process_service.py # PM4Py wrappers & mining logic
│ │ ├── exception_service.py # Failure classification & resolution
│ │ ├── decision_service.py # KPI root-cause & decision engine
│ │ ├── analytics_service.py # DuckDB deterministic calculations
│ │ ├── evidence_service.py # Provenance tracking & record matching
│ │ └── reporting_service.py # Markdown briefs and visual reports
│ │
│ ├── adapters/ # Integration boundaries
│ │ ├── process_mining/ # PM4Py adapter
│ │ ├── analytics/ # DuckDB engine adapter
│ │ ├── database/ # SQLAlchemy persistence adapter
│ │ └── workflow_engine/ # Temporal and n8n connectors
│ │
│ └── schemas/ # Pydantic V2 IO contracts
│
├── tests/
│ ├── unit/ # Service algorithms & validation tests
│ ├── integration/ # Adapters & storage tests
│ ├── protocol/ # MCP server tool invocation tests
│ └── fixtures/ # Mock event logs & transaction data
│
├── sample-data/ # Datasets for demonstrations & tests
├── demo/ # Walkthrough scripts & client configs
├── .gitignore
├── pyproject.toml
├── README.md
├── AGENTS.md # Agent operating guide
└── LICENSETesting & Quality Assurance
The codebase enforces a 4-layer testing regime:
# Run complete test suite
pytest
# Run unit tests only
pytest tests/unit
# Run MCP protocol tests (verifies tool discovery & schema contracts)
pytest tests/protocol
# Run with test coverage
pytest --cov=workflow_intelligence --cov-report=term-missingRoadmap
Initial design, protocol architecture, and AGENTS.md operational manual.
v0.1.0 (MVP): Core Pydantic schemas, PM4Py CSV log reconstruction, DuckDB analytics service, FastMCP STDIO server.
v0.5.0 (Engineering Maturity): PostgreSQL repository persistence, Temporal/n8n mock connectors, MCP Resources & Prompts, Docker Compose setup.
v1.0.0 (Production Ready): Complete CI/CD GitHub Actions, end-to-end procurement demo with synthetic ERP datasets, OpenTelemetry tracing.
v1.0.1 (Enterprise Hardening): Zero-hardcoding, dynamic SQL metric injection, universal dataset support (Amul dairy cold-chain benchmarks).
Contributing
Contributions are welcome! Please ensure that:
All business logic is encapsulated within
src/workflow_intelligence/services/, not inside tool handlers.Calculations and aggregations remain 100% deterministic.
Every new tool is backed by unit and protocol tests.
Read AGENTS.md for full architectural conventions.
License
This project is licensed under the Apache 2.0 License.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Business Observability: process inventory, AP risk, sales temperature, savings. diezX customers only
AI agents run business processes on your business data. Every change is attributed and reversible.
Register every AI agent, log every action, prove it. EU AI Act compliance built in.
AI agent governance with resolved business context, current decisions, provenance, and supersession.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceConversational business process runtime for AI agents with workflow orchestration, enterprise operations, KPI exploration, and process management capabilities.4Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables AI agents to investigate and resolve operational exceptions across orders, payments, inventory, and fulfillment through a multi-system truth and guarded actions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables users to combine CRM identity records, operational policy and ticket data, policy documents, call transcripts, and case notes, then reconcile them and identify tickets that require human escalation.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to reverse-engineer how an organization actually operates by ingesting documents, spreadsheets, chat exports, invoices and audio, then tracing every claim back to graded evidence. It supports process mining, stated-vs-enacted comparison, coverage and obligation tracking, and bilingual report generation while keeping unproven areas explicitly flagged as unknown.MIT