itsoc-icp — an MCP server over the local analysis backend

mcp-name: io.github.Ankit512/itsoc-icp

itsoc-icp (Python package itsoc_mcp) exposes this project's existing log-analysis capabilities as Model Context Protocol tools, so an MCP-capable agent (Claude Code / Claude Desktop) can drive them. It is an isolated sibling package: it imports nothing from anomaly_detector.py, changes no /api/* route, and adds no dependency to the core backend.

What it is (and is not)

• A client, not a brain. Every tool proxies the already-running local backend (http://127.0.0.1:8765 by default). This server computes no verdicts: severities, correlation, and rule verdicts are owned by the frozen deterministic detector on the backend. Tools relay; they never re-decide.
• No action execution and no approval authority. No tool can approve, reject, execute, or revoke actions. propose_block_ip can create a proposal in the pending state only; all execution and approval authority strictly resides on the backend console with human-in-the-loop step-up authentication. analyze_log kicks off log analysis and explain_finding requests an advisory explanation via the existing endpoint — an explanation never changes, suppresses, or escalates a verdict.
• Honest by construction. Backend null / "0 lines parsed" / idle states are passed through verbatim — never a fabricated all-clear or an empty file.
• Redacted by default. Any field carrying raw log text is masked through the project's existing egress choke point (console/redact.py) before it leaves, unless you opt into a trusted local session (see below).

Every tool response carries a provenance block stating: verdicts are deterministic/rule-owned, explanations are advisory, MITRE tags are derived (not verdicts), plus the running detector's detector_sha256.

Tools

Every tool declares all four MCP hints as explicit booleans (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so hosts can warn before invoke and OpenAI's directory will accept the contract. Read tools (list_runs, get_findings, get_evidence, export_run, threat_intel_lookup) are readOnlyHint: true. analyze_log, explain_finding, and propose_block_ip are writes (additive, not destructive). All backend-facing tools are openWorldHint: true.

Install

The core backend stays stdlib-only — do not install anything to run it. Install the MCP SDK only if you want to run this server:

pip install -r itsoc_mcp/requirements-mcp.txt   # the `mcp` SDK, and nothing else

Run

1. Start the backend (from the repo root), stdlib-only, no extra installs:

   sh

   python3 console/serve.py           # serves http://127.0.0.1:8765
   

2. Launch the MCP server over stdio (from the repo root):

   sh

   python -m itsoc_mcp
   

Configuration (environment)

Register with an MCP client (stdio)

Paste into your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or .mcp.json for Claude Code). Replace /ABSOLUTE/PATH/TO/itsoc with the repo root:

{
  "mcpServers": {
    "itsoc-icp": {
      "command": "python",
      "args": ["-m", "itsoc_mcp"],
      "cwd": "/ABSOLUTE/PATH/TO/itsoc",
      "env": {
        "ITSOC_BASE_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

To allow raw evidence/export on a trusted local machine, add "ITSOC_MCP_TRUSTED_LOCAL": "1" (and optionally "ITSOC_STIX_BUNDLE": "...") to that env block. The backend (python3 console/serve.py) must be running.

Tests

Network-free, no SDK, no ATT&CK cache required — the client is faked and the offline mapper is stubbed:

python3 itsoc_mcp/test_mcp.py

It asserts each tool's shape, that get_evidence/get_findings/explain_finding are redacted by default and raw only with ITSOC_MCP_TRUSTED_LOCAL=1, and that idle/unrecognized/error states return honest errors, not empty payloads.

Standalone install (uvx / pipx)

pyproject.toml builds an itsoc-icp distribution with an itsoc-icp console script (itsoc_mcp.server:main) and pins mcp>=1.9,<2 — MCP clients speak the stable 1.x API; mcp 2.0 changed the server API. The package is self-contained: designed to run with no repo checkout.

uvx itsoc-icp        # or: pipx run itsoc-icp   (the backend must still be running)

Two honesty points, stated plainly:

• The egress guard is never weakened standalone. Redaction has a single source of truth — console/redact.py — used whenever the repo is importable. In a bare install it falls back to a verbatim vendored mirror (_redact_vendored.py) that masks identically (redact-by-default; raw only with ITSOC_MCP_TRUSTED_LOCAL=1). A drift-guard test asserts the two never diverge, so the vendored copy can never silently mask less. redaction.redact_source() reports which is active. If neither could load, the module fails to import rather than pass text through — it fails closed, never open.
• threat_intel_lookup needs the repo. Its offline STIX→MITRE path reuses the repo's sibling threat_intel/ package, which a bare install does not ship. In a standalone install that one tool fails closed with an honest "offline threat-intel unavailable … NOT a clean verdict / not an all-clear" message — never a fabricated match or a fake all-clear. Run from the repo (python -m itsoc_mcp) to use offline threat-intel. Every other tool is a client of the backend API and works identically standalone or in-repo.

Standalone means no repo checkout is needed for the MCP package — the backend (python3 console/serve.py) still runs separately and must be reachable at ITSOC_BASE_URL.

License

MIT — see the repository's top-level LICENSE.