Threat Actors

`list_threat_actors`

List tracked threat actors, ranked by how much corroborated evidence exists for each (techniques + campaigns + CVEs + industries + malware). Optionally filter by type: ransomware, apt, cybercrime, hacktivist. Returns name, slug, origin, motivation and per-category counts. Use the slug with get_threat_actor for the full dossier. Costs 1 credit.

POST

tools/call

Cost: 1 credit per successful call · Response shape: jsonb

Parameters

limitintegeroptional

1–100. Defaults to 25.

actor_typestringoptional

Filter by type: ransomware, apt, cybercrime, hacktivist, unknown. Omit for all types.

Example invocation

Ask your agent:

Which ransomware groups does Precursor track most closely? Give me the top 5 and what makes each one well documented.

Raw JSON-RPC:

curl -s https://api.precursorintelligence.com/functions/v1/mcp \
  -H "Authorization: Bearer $PRECURSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_threat_actors",
      "arguments": { "actor_type": "ransomware", "limit": 5 }
    }
  }'

Response

result.content[0].text (parsed)

{
  "count": 5,
  "total": 388,
  "limit": 5,
  "actor_type": "ransomware",
  "items": [
    {
      "name": "SafePay",
      "slug": "safepay",
      "actor_type": "ransomware",
      "suspected_origin_country": "Unknown (Russian-speaking nexus suspected; the encryptor aborts on Cyrillic keyboard layouts)",
      "motivation": "financial",
      "first_seen": "2024-09-01",
      "last_seen": "2025-07-01",
      "counts": {
        "techniques": 168, "campaigns": 3, "cves": 2,
        "industries": 8, "malware": 4
      }
    }
  ],
  "generated_at": "2026-08-04T10:20:34.843Z"
}

How the ranking works

A plain sum of the five counts values — no hidden weighting. Every component is returned, so an agent can explain the order or re-rank on its own axis (for example, CVE count only, when the question is about patching).

Ranking changed

This tool used to rank by how often an actor's name appeared in scraped security blogs, which measured press coverage rather than activity. It is now evidence-based, and the payload fields changed with it.

total vs count

total is how many actors matched the filter overall; count is how many were returned. If they differ, there is more to fetch — raise limit.

get_threat_actor — full dossier for one actor.
list_threat_actors_by_industry — narrow to actors targeting a sector.

Errors

Code	Message	When
`-32602`	`invalid_params: limit: range`	`limit` is outside 1–100.
`-32602`	`invalid_params: actor_type: pattern`	`actor_type` contains characters outside `[A-Za-z0-9 _-]`.
`-32001`	`unauthorized`	Key is invalid or revoked.
`-32002`	`insufficient_credits`	Organisation credit balance is below 1.

An actor_type that is well-formed but matches nothing returns a successful response with an empty items array and total: 0. The credit is charged.