MCP-SOC Middleware

MCP-Based Middleware for Integrating Agentic AI with Legacy SOC Infrastructure

PMICS Batch 05 | University of Dhaka, Department of CSE
CSE-810: Project on Cyber Security
Authors: Md. Abdullah Bin Salaam (H-28) · Ovishek Pal (H-54)
Supervisor: Prof. Dr. Mamun Or Rashid

---

One-Command Startup

git clone https://github.com/your-org/mcp-soc-middleware.git && cd mcp-soc-middleware
cp .env.example .env          # fill in ANTHROPIC_API_KEY at minimum
docker compose up -d          # starts all 5 services

Wait ~90 seconds for Splunk and TheHive to initialise, then visit:

Service	URL	Default credentials
MCP Middleware API	http://localhost:8000/docs	Bearer: mcp-dev-token-change-me-in-production-abc123
Splunk Web UI	http://localhost:8001	admin / changeme123!
TheHive	http://localhost:9000	admin@thehive.local / secret
Cortex	http://localhost:9001	(first-run wizard)
Elasticsearch	http://localhost:9200	(no auth in dev)

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   AI Agent Layer                     │
│         (SOCOrchestrator + Anthropic Claude)         │
└───────────────────────┬─────────────────────────────┘
                        │  MCP  (Bearer Token)
┌───────────────────────▼─────────────────────────────┐
│          MCP Unified Access Layer  :8000             │
│   FastAPI · ToolRegistry · AuditLog · RateLimit      │
└──────────┬────────────────────────┬─────────────────┘
           │                        │
┌──────────▼──────────┐  ┌──────────▼──────────────┐
│   SplunkAdapter     │  │   TheHiveAdapter         │
│  5 MCP tools        │  │  7 MCP tools             │
└──────────┬──────────┘  └──────────┬───────────────┘
           │                        │
┌──────────▼──────────┐  ┌──────────▼──────────────┐
│  Splunk Enterprise  │  │  TheHive 5 + ES 7        │
│  REST API :8089     │  │  REST API :9000          │
└─────────────────────┘  └─────────────────────────┘

---

Project Structure

mcp-soc-middleware/
├── mcp_server/                  # FastAPI MCP server package
│   ├── main.py                  # App factory, lifespan, MCP endpoints
│   ├── core/
│   │   ├── registry.py          # Dynamic tool registry and adapter loader
│   │   └── auth.py              # Bearer token authentication dependency
│   ├── adapters/
│   │   ├── base_adapter.py      # Abstract adapter contract
│   │   ├── splunk_adapter.py    # Splunk SIEM adapter (5 tools)
│   │   └── thehive_adapter.py   # TheHive SOAR adapter (7 tools)
│   ├── middleware/
│   │   ├── audit.py             # JSONL audit logging middleware
│   │   └── rate_limit.py        # slowapi rate limiter
│   ├── models/
│   │   ├── tool_models.py       # MCP ToolDefinition, Request, Response models
│   │   └── alert_models.py      # Normalised alert / observable schemas
│   └── utils/                   # (extensible — logging helpers, etc.)
│
├── agent/
│   ├── orchestrator.py          # ReAct loop + MCP client + Anthropic API
│   ├── workflows/
│   │   └── triage_workflow.py   # Pre-built task strings for common workflows
│   └── prompts/                 # (extensible — prompt template files)
│
├── config/
│   └── settings.py              # Pydantic-Settings configuration model
│
├── tests/
│   ├── unit/adapters/
│   │   ├── test_splunk_adapter.py
│   │   └── test_thehive_adapter.py
│   ├── integration/             # (full end-to-end tests against live services)
│   └── fixtures/                # Shared test data and factory-boy factories
│
├── scripts/
│   ├── bootstrap.sh             # One-time local setup (venv + .env)
│   └── splunk_bootstrap.sh      # Generate Splunk API token post-startup
│
├── docker/
│   ├── Dockerfile               # Multi-stage image for mcp-middleware service
│   ├── splunk/
│   │   ├── inputs.conf          # Splunk monitor stanza for sample data
│   │   └── sample_alerts.json   # Synthetic SOC alerts for dev seeding
│   └── thehive/
│       └── application.conf     # TheHive minimal config pointing to ES
│
├── logs/                        # Audit JSONL logs (git-ignored)
├── docs/                        # Architecture diagrams and runbooks
├── docker-compose.yml           # Full local dev stack (5 services)
├── requirements.txt             # Pinned Python dependencies
├── pyproject.toml               # Build config, ruff, mypy, pytest settings
├── .env.example                 # All required environment variables with defaults
└── README.md                    # This file

---

Local Development (without Docker)

# 1. Bootstrap virtual environment
bash scripts/bootstrap.sh
source .venv/bin/activate

# 2. Start only the platform dependencies via Docker
docker compose up -d splunk elasticsearch thehive

# 3. Generate a Splunk API token (first time only)
bash scripts/splunk_bootstrap.sh
# → Paste the printed token into .env as SPLUNK_TOKEN=...

# 4. Run the MCP server
python -m mcp_server.main
# Server starts at http://localhost:8000

# 5. In a separate terminal: run the AI agent on a triage task
python - <<'EOF'
import asyncio
from agent.orchestrator import SOCOrchestrator
from agent.workflows.triage_workflow import alert_triage_task

async def main():
    agent = SOCOrchestrator()
    result = await agent.run(alert_triage_task(time_window="-4h", severity="high"))
    print(result)

asyncio.run(main())
EOF

---

Running Tests

pytest                          # all tests with coverage
pytest tests/unit -v            # unit tests only (no live services needed)
pytest tests/integration -v     # requires docker compose up -d

---

MCP API Reference

All endpoints require Authorization: Bearer <MCP_BEARER_TOKEN>.

GET /tools/list

Returns the full tool catalogue (12 tools across Splunk + TheHive adapters).

POST /tools/call

{
  "name": "splunk.search_alerts",
  "arguments": {
    "severity": "high",
    "earliest": "-4h",
    "limit": 50
  }
}

Available Tools

Tool	Platform	Description
splunk.search_alerts	Splunk	Search notable events by severity/time
splunk.get_alert_details	Splunk	Full field set for one event ID
splunk.search_events	Splunk	Arbitrary SPL query
splunk.get_index_summary	Splunk	Available indexes and sourcetypes
splunk.acknowledge_notable	Splunk	Update notable event status/owner
thehive.create_case	TheHive	Create a new case
thehive.get_case	TheHive	Retrieve case by ID
thehive.list_cases	TheHive	List cases by status/severity
thehive.create_alert	TheHive	Create an alert from external data
thehive.add_observable	TheHive	Add IP/domain/hash/URL to a case
thehive.update_case_status	TheHive	Update status and add summary note
thehive.add_task	TheHive	Create an analyst task inside a case

---

Extending with a New Adapter

1. Create mcp_server/adapters/my_tool_adapter.py inheriting BaseAdapter.
2. Implement register_tools() returning your ToolDefinition list.
3. Expose module-level register_tools(), adapter_setup(), adapter_teardown() functions.
4. Add the module path to ADAPTER_MODULES in mcp_server/main.py.

No changes to the registry, middleware, or AI agent are required.

---

Environment Variables

See .env.example for the full annotated list. Minimum required for local dev:

ANTHROPIC_API_KEY=sk-ant-api03-...   # required for AI agent
MCP_BEARER_TOKEN=...                  # any strong random string
SPLUNK_TOKEN=...                      # from scripts/splunk_bootstrap.sh
THEHIVE_API_KEY=...                   # from TheHive UI → Admin → Users

---

License

MIT © 2026 Md. Abdullah Bin Salaam & Ovishek Pal