ThreatConnect v3 MCP Server

A Model Context Protocol server that gives an MCP-capable LLM client a small set of reliable, validated tools to drive ThreatConnect Case Management and Threat Intelligence through the v3 REST API.

It hides v3's HMAC authentication, retries, pagination, and error quirks behind typed tools so the model never hand-rolls HTTP or signing.

Tools

There is deliberately no generic write tool: unconstrained PUT/DELETE against shared threat intel is too dangerous to hand an LLM.

Related MCP server: Threat.Zone MCP Server

Install

Requires Python 3.12+ and uv.

uv sync
cp .env.example .env   # then fill in your credentials

Configuration

Set these in .env (or the environment). HMAC is the primary auth path.

Clock skew: the HMAC Timestamp must be within five minutes of server time. Keep the host on NTP.

Run

uv run tc-mcp          # stdio transport

Claude Desktop / mcp.json

{
  "mcpServers": {
    "threatconnect": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/threat_connect_mcp", "run", "tc-mcp"]
    }
  }
}

Inspect the tool surface

npx @modelcontextprotocol/inspector uv run tc-mcp

Development

uv run ruff check .        # lint
uv run mypy src            # types
uv run pytest -q           # mocked unit/integration tests

Live smoke test (gated)

The live tests are skipped unless credentials are present and -m live is passed. A green test_signature proves the HMAC string-to-sign is correct against your instance:

TC_BASE_URL=... TC_API_ACCESS_ID=... TC_API_SECRET_KEY=... \
    uv run pytest -m live tests/test_live.py

Design notes

• Thin httpx client, not TcEx. TcEx assumes it runs inside the TC platform; a small signed httpx client is easier to test (golden HMAC vector) and has no hidden runtime assumptions.

• "Dynamic" via schema introspection. Tools validate caller fields/types against the live OPTIONS /v3/<endpoint> and /v3/artifactTypes descriptors, so they track the API instead of a frozen copy. Validation degrades gracefully if a descriptor is unavailable — the API stays the final authority.

• TQL injection defense. Any caller value interpolated into a TQL clause (enrich-by-summary) is escaped and control characters are rejected.