Submit
solomonneas

cortex-mcp

Community solomonneas
Updated

MCP server for Cortex observable analysis and response engine

cortex-mcp

TypeScriptNode.jsMCPLicense: MIT

An MCP (Model Context Protocol) server for Cortex - the observable analysis and active response engine by StrangeBee/TheHive Project.

Cortex automates the analysis of observables (IPs, URLs, hashes, domains, emails, files) using analyzers and can execute response actions via responders. This MCP server exposes Cortex's full analysis pipeline to LLMs, enabling AI-driven observable enrichment and automated response orchestration.

Features

  • 12 MCP tools covering analyzers, jobs, responders, and bulk operations
  • 2 MCP resources for browsing Cortex state
  • 2 MCP prompts with guided investigation workflows
  • Full TLP/PAP support for data classification
  • Bulk analysis across all applicable analyzers with taxonomy aggregation
  • Structured error handling with meaningful messages

Prerequisites

  • Node.js 20 or later
  • A running Cortex instance (v3.x recommended)
  • A Cortex API key with appropriate permissions

Installation

git clone https://github.com/solomonneas/cortex-mcp.git
cd cortex-mcp
npm install
npm run build

Configuration

Set these environment variables before running the server:

Variable Required Default Description
CORTEX_URL Yes - Cortex base URL (e.g., https://cortex.example.com:9001)
CORTEX_API_KEY Yes - API key for authentication
CORTEX_VERIFY_SSL No true Set to false to skip SSL verification

Example .env file:

CORTEX_URL=https://cortex.example.com:9001
CORTEX_API_KEY=your-api-key-here
CORTEX_VERIFY_SSL=true

Usage

With Claude Desktop

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/path/to/cortex-mcp/dist/index.js"],
      "env": {
        "CORTEX_URL": "https://cortex.example.com:9001",
        "CORTEX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Standalone

export CORTEX_URL=https://cortex.example.com:9001
export CORTEX_API_KEY=your-api-key-here
npm start

Development

export CORTEX_URL=https://cortex.example.com:9001
export CORTEX_API_KEY=your-api-key-here
npm run dev

MCP Tools

Analyzer Tools

Tool Description
cortex_list_analyzers List all enabled analyzers, optionally filtered by data type
cortex_get_analyzer Get details about a specific analyzer by ID
cortex_run_analyzer Submit an observable to a specific analyzer for analysis
cortex_run_analyzer_by_name Run an analyzer by name instead of ID (convenience wrapper)

Job Tools

Tool Description
cortex_get_job Get the status and details of an analysis job
cortex_get_job_report Get the full report of a completed analysis job
cortex_wait_and_get_report Wait for a job to complete and return the report
cortex_list_jobs List recent analysis jobs with optional filters
cortex_get_job_artifacts Get artifacts (extracted IOCs) from a completed job

Responder Tools

Tool Description
cortex_list_responders List all enabled responders, optionally filtered by data type
cortex_run_responder Execute a responder action against a TheHive entity

Bulk Operations

Tool Description
cortex_analyze_observable Run ALL applicable analyzers and return aggregated results with taxonomy summary

MCP Resources

URI Description
cortex://analyzers List of all enabled analyzers with capabilities
cortex://jobs/recent Last 50 analysis jobs

MCP Prompts

Prompt Description
analyze-observable Guided workflow for analyzing an observable through Cortex
investigate-ioc Deep investigation workflow for a suspicious IOC

Examples

Analyze an IP address

Use cortex_analyze_observable to check the IP 185.220.101.42
with dataType "ip", tlp 2, pap 2.

The server will submit the IP to all analyzers that support the ip data type (VirusTotal, AbuseIPDB, etc.), wait for results, and return an aggregated report with taxonomy counts:

{
  "observable": { "dataType": "ip", "data": "185.220.101.42" },
  "analyzersRun": 4,
  "summary": {
    "malicious": 2,
    "suspicious": 1,
    "info": 1,
    "safe": 0
  },
  "results": [...]
}

Run a specific analyzer

Use cortex_run_analyzer_by_name with analyzerName "VirusTotal",
dataType "hash", data "44d88612fea8a8f36de82e1278abb02f"

Check job status

Use cortex_get_job with jobId "AWl2d8x1kDx6FO7wxPBn"

Execute a responder

Use cortex_run_responder with responderId "Mailer_1_0",
objectType "case_artifact", objectId "~123456"

Supported Data Types

Type Examples
ip 8.8.8.8, 2001:db8::1
domain example.com
url https://malware.example.com/payload
fqdn mail.example.com
hash MD5, SHA1, SHA256 hashes
mail [email protected]
filename malware.exe
registry HKLM\Software\Malware
regexp Regular expression patterns
other Any other observable type

Testing

npm test            # Run all tests
npm run test:watch  # Run in watch mode
npm run lint        # Type check only

Project Structure

cortex-mcp/
  src/
    index.ts              # MCP server entry point
    config.ts             # Environment config + validation
    client.ts             # Cortex REST API client
    types.ts              # Cortex API type definitions
    resources.ts          # MCP resources
    prompts.ts            # MCP prompts
    tools/
      analyzers.ts        # Analyzer tools
      jobs.ts             # Job management tools
      responders.ts       # Responder tools
      bulk.ts             # Bulk operations
  tests/
    client.test.ts        # API client unit tests
    tools.test.ts         # Tool handler unit tests
  package.json
  tsconfig.json
  tsup.config.ts
  vitest.config.ts

License

MIT

MCP Server · Populars

MCP Server · New