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.