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

Tool	v3 call	What it does
create_case	POST /v3/cases	Create a case (name/status/severity + optional nested artifacts, tags, attributes).
update_case	PUT /v3/cases/{id}	Partial update; nested associations honor mode (append/replace/delete).
create_indicator	POST /v3/indicators	Create any indicator type; type→summary-field resolved automatically.
add_artifact	POST /v3/artifacts	Attach one artifact to an existing case by case_id/case_xid.
add_artifacts_bulk	PUT /v3/cases/{id} or fan-out POST	Attach many artifacts: one nested-append request, or concurrent POSTs with a per-item ledger.
enrich_indicator	GET /v3/indicators/{id|summary}	Return TC's context: rating/confidence, tags, attributes, associations, observations, web link.
tc_get (read-only)	GET /v3/<allowlisted>	Escape hatch for arbitrary reads with TQL/fields — never writes.

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

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.

Variable	Required	Default	Notes
TC_BASE_URL	yes	—	e.g. https://myinstance.threatconnect.com (normalized to /api).
TC_API_ACCESS_ID	HMAC	—	API user access id.
TC_API_SECRET_KEY	HMAC	—	API user secret key (never logged).
TC_API_TOKEN	token	—	Alternative to HMAC; used only if the HMAC pair is absent.
TC_DEFAULT_OWNER	no	—	Default owner for owner-relative reads/writes.
TC_TIMEOUT	no	30	Per-request timeout (seconds).
TC_MAX_RETRIES	no	3	Retries on 429/5xx with backoff + jitter.
TC_VERIFY_SSL	no	true	TLS verification.
TC_LOG_LEVEL	no	WARNING	Logs go to stderr, secret-redacted.

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.